Subgraph API Keys

A subgraph API key provides access to a specific subgraph within a variant, or a set of subgraph-variant pairs, within your organization's graph.

Use subgraph keys when you need to run checks on existing subgraphs or publish updates to their schemas in CI/CD pipelines. A subgraph key is scoped to subgraphs that already exist in a variant, so you can't create a key for a subgraph that hasn't been created yet. To add a new subgraph, publish it once with another credential, such as a personal, graph, or operator API key. Then create a subgraph key for it. Create one subgraph API key per pipeline workflow.

Subgraph keys expire one year from creation.

Create a subgraph API key using GraphOS Studio

1. Go to studio.apollographql.com.

2. Select the API Keys tab.

3. Select Create API key.

4. Give your key a name, such as Production. This helps you keep track of how each API key is used.

5. Select Subgraph API key as the key type.

6. Under Resources, select the graph, variant, and subgraph you want to grant access to. The selector lists only subgraphs that already exist in the variant. You can add multiple subgraphs by selecting Add subgraph resource.

7. Select Create.

8. Copy the key's value and store it in a secure location. For security reasons, you can't view an API key's value again after you close this modal.

Create a subgraph API key using the Rover CLI

Run rover api-key create with a subgraph configuration file for the subgraphs you want to grant access to. See the rover api-key create command documentation.

Create a subgraph API key using the Platform API

To create a subgraph API key, use the createKey mutation from the Platform API.

Before you start, gather:

• Your organization ID, from the Organization tab in Studio

• The subgraph you want to grant access to (graph ID, subgraph name, and variant)

The graph, variant, and subgraph must already exist. If any of them doesn't, or if the subgraph has been deleted, createKey returns the error Graph, variant, or subgraph information is incorrect.

Use this mutation:

mutation Mutation($organizationId: ID!, $name: String!, $type: GraphOsKeyType!, $resources: ApiKeyResourceInput) {  
  organization(id: $organizationId) {    
    createKey(name: $name, type: $type, resources: $resources) {      
      keyName      
      id      
      token    
    }
  }
}

Include a request payload with the following properties, using your own values:

{
  "name": <YOUR_SUBGRAPH_API_KEY_NAME>,
  "type": "SUBGRAPH",
  "organizationId": <YOUR_ORGANIZATION_ID>,
  "resources": {
    "subgraphs": [
      {
        "graphId": <YOUR_GRAPH_ID>,
        "subgraphName": <YOUR_SUBGRAPH_NAME>,
        "variantName": <YOUR_VARIANT_NAME_1>
      },
      {
        "graphId": <YOUR_GRAPH_ID>,
        "subgraphName": <YOUR_SUBGRAPH_NAME>,
        "variantName": <YOUR_VARIANT_NAME_2>
      }
    ]
  }
}

Example response payload:

{
  "data": {
    "organization": {
      "createKey": {
        "keyName": "Subgraph test key",
        "id": "6ca72032-535a-4bba-b816-fa8d88823863",
        "token": "ak_v2_RkZFMjE4ODYtMzk5Qy00QkMzLUExRDYtMDRBMjE5NTdFNTdF_MUU3M0MxQ0MtMjY5OS00QjhBLTk4MjYtQzVFMUJFRjFBQUZB"
     }
    }
  }
}

Copy the key's value and store it in a secure location. You can't view an API key's value after you create it.

For an overview of all key types, see API Keys.