Connecting and authenticating with the Explorer
The Explorer automatically attempts to connect to your GraphQL server at the URL specified in its Settings tab.
When you use the Explorer with a cloud supergraph, the endpoint URL is always the URL of your current variant's GraphOS-managed router.
Depending on your GraphQL server's settings, you might need to configure the Explorer's connection to handle CORS requirements or authentication.
Requests from the Explorer go straight from your browser to your GraphQL server, so your endpoint will see requests coming from the
It's common for public endpoints to have CORS policies that restrict which domains can query them. If your endpoint has CORS protections enabled, you probably need to safelist
https://studio.apollographql.com in your CORS policy to use the Explorer.
To do so, include the following header(s) in your server's responses:
Access-Control-Allow-Origin: https://studio.apollographql.com# Include this one only if your server also authenticates via cookies.Access-Control-Allow-Credentials: true
If you can't change your CORS policy, you might be able to create a proxy for your endpoint and point the Explorer to the proxy instead. CORS policies are enforced by browsers, and the proxy won't have the same issues communicating to your endpoint.
If your graph has authentication requirements that aren't covered by these options, please contact email@example.com with questions or feedback.
The bottom panel of the Explorer includes a Headers tab where you can set headers that are included in your operation's HTTP request.
Headers can include the values of environment variables, which are specified with double curly braces as shown:
To set this up, your cookie's value must contain
SameSite=None; Secure. Additionally, these CORS headers must be present in your server's response to Studio:
Access-Control-Allow-Origin: https://studio.apollographql.comAccess-Control-Allow-Credentials: true
Once configured, requests sent from
https://studio.apollographql.com will carry the cookies from your domain when you run queries with the Explorer. If you're logged in on your domain, requests from the Explorer will also be logged in. If you log out on your domain and the cookie is removed, requests from the Explorer will be logged out.
The Explorer's Settings tab includes a section for providing Environment Variables. Here, you can provide sensitive information that you can then include in header values or preflight scripts. This enables you to share operations (including headers) with other team members without exposing sensitive data.
For example, you can define a
token environment variable like so:
You can then include that environment variable in header values with double curly braces, as shown:
If you share this operation with team members, your value for
token is not shared, and other users can provide their own value.
Similar to tools like Postman, the Explorer can run a custom preflight script before each GraphQL operation that's executed by your team members. This script is identical for every team member that uses the Explorer with a particular variant. Preflight scripts are especially useful for managing authentication flows like OAuth, for example by refreshing an access token.
Each preflight script applies to a single variant of a particular graph, so you can define different scripts for each of your graph's environments.
- All team members with access to a variant can view that variant's preflight script.
- For protected variants, only organization members with the
Graph Adminrole can create or edit a variant's preflight script.
- For non-protected variants, members with the
Contributorrole can also modify the preflight script.
- For non-protected variants, members with the
- Preflight scripts are stored in the Apollo cloud in plaintext.
- Do not include secret credentials in preflight scripts! Instead, team members can provide their individual credentials in the Explorer via environment variables.
- Team members can disable the execution of a preflight script.
To create a preflight script:
Open Apollo Studio and then open the Explorer for the graph and variant you want to create a script for.
Open the Explorer's Settings tab and scroll down to the Preflight script section:
Click Add script. The following dialog appears:
Click Show snippets to display a list of common helpful actions you can perform from your preflight script (such as sending HTTP requests and interacting with Explorer environment variables).
Develop your script in the Script editor panel. As you develop, you can click Test script to test its execution. Console messages are printed in the Console output panel.
When your script is ready, click Save. Studio stores your script.
You're done! After you save your script, it's automatically loaded for any team member that uses the Explorer with the associated variant.
These symbols are available within the scope of a preflight script. Snippets for each are available via the Show snippets link in the preflight script dialog.
Function that returns the current value of the environment variable with the specified
Function that sets a new value for the environment variable with the specified
Function for making HTTP requests to external services from within a preflight script.
Network requests are initiated from an origin of
Function that [rompt the user for input and returns the value in a promise. If the user cancels the prompt, the promise resolves to
The prompt supports Markdown rendering of the
The body of the
This exposes the
By default, a variant's preflight script runs automatically before every GraphQL operation that's executed in the Explorer. Team members can temporarily disable the script from the Preflight script section of the Settings tab. To do so, toggle the switch to OFF: