Docs
Launch GraphOS Studio

Connecting and authenticating with the Explorer

The automatically attempts to connect to your GraphQL server at the URL specified in its Settings tab.

When you use the 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 's connection to handle CORS requirements or authentication.

CORS policies

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

It's common for public endpoints to set 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 .

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

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


# 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 to the proxy instead. CORS policies are enforced by browsers, and the proxy won't have the same issues communicating with your endpoint.

Authentication

The provides features to help you authenticate via request headers, cookies, and 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 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 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, the following CORS headers must be present in your server's response to Studio:

Access-Control-Allow-Origin: https://studio.apollographql.com
Access-Control-Allow-Credentials: true

Once configured, requests sent from https://studio.apollographql.com include the cookies from your domain when you run queries with the . 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 's Settings tab includes a section for defining environment s. Here, you can provide sensitive information that you can then inject into header values, GraphQL variables, or scripts. This enables you to share s (including their headers) with other team members without exposing this sensitive data.

Defining

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

Setting Explorer environment variables

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

Injecting

You can inject your environment s into any of the following:

Header values

Inject an environment into an HTTP header value by surrounding the variable's name with double curly braces, as shown:

Setting Explorer headers with environment variables
GraphQL variables

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

Setting Explorer graphql variables with environment variables
Custom scripts

If you create a custom script that runs before an executes, that script can access an environment 's value like so:

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

Scripting

Similar to tools like Postman, the can run custom scripts when executing each GraphQL . These JavaScript-based scripts often populate the values of environment variables that are then injected into HTTP header values or GraphQL s. This can be especially useful for managing authentication flows like OAuth, for example by refreshing an expired access token, or validating response data. For an example, see Operation Scripts.

Script types

You can define two different types of scripts:

  • Preflight scripts. You can define a single preflight script per variant of a graph. This script runs before every Explorer operation that's executed against the associated (unless a user individually disables the script).
    • Preflight scripts are especially helpful for enabling organization-wide authentication against your graph.
  • Operation scripts. If you use operation collections, you can define a separate script for each saved in a collection. This script can then control everything that happens before, during, and after an operation is executed (as long as a user individually enables the script).
    • scripts are especially helpful for debugging the behavior of individual operations when they're provided various values.

If an runs both types of scripts, the preflight script runs before the script.

Important considerations for Explorer scripts

  • Scripts are stored in the Apollo cloud in plaintext.
    • Do not include secret credentials in scripts! Instead, team members can provide their individual credentials to the via environment variables.
  • If a team member has view access to a particular graph or collection, that team member can also view any scripts associated with that /collection.
  • Preflight scripts are enabled by default, and individual team members can disable them.
  • scripts are disabled by default, and individual team members can enable them.

Preflight scripts

Creating preflight scripts

For protected variants, only organization members with the Graph Admin role can create or edit a 's preflight script.

For non-protected s, members with the Contributor role can also modify the preflight script.

To create a preflight script:

  1. Open GraphOS Studio and then open the for the graph and you want to create a script for.

  2. Open the 's Settings tab and scroll down to the Preflight script section:

    Preflight script settings in the Explorer

  3. Click Add script. The following dialog appears:

    Editing preflight scripts in the Explorer

  4. 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 environment s).

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

  6. 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 with the associated .

Disabling preflight scripts

By default, a 's preflight script runs automatically before every GraphQL that's executed in the . Team members can individually disable the script from the Personal Settings > Scripts section of the 's Settings tab:

Disabling preflight scripts in the Explorer

To do so, toggle the switch to OFF.

Operation scripts

Creating operation scripts

You can only create scripts for operations that are saved in an operation collection.

Only organization members with edit access to a particular collection can create or edit operation scripts for that collection.

  1. From the , open an from the Operation Collections menu:

    Selecting an operation

  2. From the 's bottom panel, select the Script tab and click + Add Script:

    Adding a new operation script

    The following modal appears:

    Editing operation scripts in the Explorer

  3. Create, test, and save your script.

Enabling operation scripts

By default, scripts are disabled for each individual user. Users can enable scripts from the 's Settings tab:

Editing operation scripts in the Explorer

Chaining operations

A script can use the explorer.runOperation function to execute another that's saved in a collection. That operation might in turn have its own script, which can also call explorer.runOperation.

You can use this mechanism to chain together a sequence of s for more advanced authentication flows.

Scripting API reference

These symbols are available within the scope of both preflight scripts and scripts. Snippets for these symbols are available via the Show snippets link in the scripting dialog.

Name /
Type		Description
explorer.environment.get

(key: string) => Readonly

Function that returns the current value of the environment with the specified key.

explorer.environment.set

(key: string, value: JSONValue) => void

Function that sets a new value for the environment 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 script.

Network requests are initiated from an origin of https://preflight-request.apollographql.com. Make sure the appropriate CORS headers are sent for those requests.

explorer.runOperation

(options: { scope?: 'personal' | 'shared' | 'sandbox'; graphRef?: string | null; collectionName: string; operationName: string; headers?: Record<string, string>; variables?: JSONObject; }) => Promise<{ result: ExecutionResult<JSONObject> | undefined; code: number; }>

Function for executing other saved s. If the target operation has defined its own script, it will run before its operation.

  • If scope is sandbox, graphRef defaults to null.
  • If graphRef is null, scope defaults to 'sandbox'.
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.oauth2Request

(authUrl: string, queryParams?: Record<string, string>) => Promise<Record<string, string> | null>

Function that prompts the user to authenticate using your OAuth 2.0 provider's URL (specified by authUrl). Provide any required query parameters to the auth endpoint via the queryParams parameter.

This function returns a promise containing the query parameters from your OAuth provider's response. If the user cancels the prompt, the promise resolves to null.

For OAuth 2.0 authentication to work with the , your OAuth 2.0 provider must recognize https://studio.apollographql.com/explorer-oauth2 as a valid redirect URL. You can configure this in your OAuth 2.0 provider settings when you set up a new client or application.

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 .

explorer.CryptoJS

This exposes the crypto-js package for use within your script. For available functions, see the documentation.

Examples

Operation Scripts

Here is a small example that runs an and sets an environment for use on future operations:

const response = await explorer.runOperation({
 scope: 'shared',
 graphRef: 'SpaceX-pxxbxen@current',
 collectionName: 'Mission Control',
 operationName: 'Ships',
})


const firstShipID = response.result.data.ships[0].id


explorer.environment.set('shipID', firstShipID)
Previous
GraphQL subscription support
Next
Embedding
Edit on GitHubEditForumsDiscord