Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Start for Free

Connecting and Authenticating with the Explorer

Configure the Explorer to connect to your GraphQL server

The Explorer automatically attempts to connect to your 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 's -managed .

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 sees requests coming from this domain:

It's common for public endpoints to set CORS policies that restrict which domains can them. If your endpoint has CORS protections enabled, you probably need to safelist in your CORS policy to use the Explorer.

To do so, include the following header(s) in your server's responses:

# Include this 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 with your endpoint.


The Explorer provides features to help you authenticate via request headers, cookies, and scripts.


If your has authentication requirements that aren't covered by these options, please contact 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 's HTTP request.

Headers can include the values of environment variables, which are injected using double curly braces.

For example, a header with the key Authorization could have the value Bearer {{token}}.


If your server uses cookies to authenticate, you can configure your endpoint to share those cookies with

To set this up, your cookie's value must contain SameSite=None; Secure. Additionally, the following CORS headers must be present in your server's response to Studio:

Access-Control-Allow-Credentials: true

Once configured, requests sent from include 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.

Cookies for Safari users

Safari 13.1 and later blocks third-party cookies by default. When using Explorer in Safari, it considers your server's endpoint to be "third-party" to . Therefore, Safari users need to open Settings > Privacy in Safari and deselect Prevent cross-site tracking to send Explorer requests with cookies.

Environment variables

The Explorer's Settings tab includes a section for defining environment variables. Here, you can provide sensitive information that you can then inject into header values, variables, or scripts. This lets you share (including their headers) with other team members without exposing this sensitive data.


You define environment variables in the Explorer's Settings tab, like so:

"exampleToken": "tokenValue"

If you share an operation that uses environment variables with your team members, your values for those environment variables are not shared, and other users can provide their own values.


You can inject your Explorer environment variables into any of the following:

Header values

Inject an environment variable into an HTTP header value by surrounding the variable's name with double curly braces. For example, a header with the key Authorization could have the value Bearer {{token}}.

GraphQL variables

Inject an environment variable into a GraphQL variable value by surrounding the variable's name with double curly braces, like so:

"token": "{{token}}"
Custom scripts

If you create a preflight or operation script, that script can access an environment variable's value like so:

const secretToken = explorer.environment.get('token');

Check out the Explorer scripting docs to learn how you can use preflight scripts for authentication purposes.

GraphQL Subscription Support
Custom Scripts
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy