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.

CORS policies

Requests from the Explorer go straight from your browser to your GraphQL server, so your endpoint will see requests coming from the https://studio.apollographql.com domain.

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:

1
Access-Control-Allow-Origin: https://studio.apollographql.com
2

3
# Include this one only if your server also authenticates via cookies.
4
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.

Authentication

The Explorer currently enables you to authenticate via request headers, cookies, and preflight scripts.

If your graph has authentication requirements that aren't covered by these options, please contact support@apollographql.com with questions or feedback.

Request headers

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:

Setting Explorer headers with environment variables

Cookies

If your server uses cookies to authenticate, you can configure your endpoint to share those cookies with https://studio.apollographql.com.

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:

1
Access-Control-Allow-Origin: https://studio.apollographql.com
2
Access-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.

Environment variables

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.

Preflight scripts

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.

⚠️ Important considerations for preflight scripts

All team members with access to a variant can view that variant's preflight script.
For protected variants, only organization members with the Graph Admin role can create or edit a variant's preflight script.
- For non-protected variants, members with the Contributor role can also modify the preflight script.
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.

Creating 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.

Preflight script API reference

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.

Name / Type	Description
`explorer.environment.get` `(key: string) => Readonly`	Function that returns the current value of the environment variable with the specified `key`.
`explorer.environment.set` `(key: string, value: JSONValue) => void`	Function that sets a new value for the environment variable with the specified `key`.
`explorer.fetch` `(href: string, options?: { method?: string, body?: string \| null, headers?: Record<string, string>, credentials: 'include' \| 'omit' \| 'same-origin' }) => Promise<{ code: number, body: string, json: () => any }>`	Function for making HTTP requests to external services from within a preflight script. Network requests are initiated from an origin of `https://preflight-request.apollographql.com`, please ensure the appropriate CORS headers are sent for those requests.
`explorer.prompt` `(msg: string, defaultResponse?: string) => Promise<string \| null>`	Function that prompts the user for input and returns the value in a promise. If the user cancels the prompt, the promise resolves to `null`. The prompt supports Markdown rendering of the `msg` parameter.
`explorer.request.body` `{ query: string; variables: { [key in string]?: JSONValue } \| null; operationName: string \| undefined; }`	The body of the `POST` request that's sent to the configured GraphQL endpoint for the current operation.
`explorer.CryptoJS`	This exposes the `crypto-js` package for use within your preflight script. For available functions, see the documentation.

Disabling preflight scripts

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: