Subgraph API Keys

Authenticate CI/CD and automation to specific subgraphs in GraphOS

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 subgraphs, create subgraphs, or publish updates to subgraph schemas in CI/CD pipelines. Create one subgraph API key per pipeline workflow.

Subgraph keys expire one year from creation.

note
Only organization members with the Org Admin or Graph Admin role on an Enterprise plan or Standard plan can create subgraph API keys. Customers on Standard plans may create up to 5 subgraph keys. Enterprise plans have no limit on subgraph keys.Only organization members with the Org Admin role can manage subgraph API keys in the following ways: view all subgraph keys, view a single subgraph key, and delete a subgraph key.

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)

Use this mutation:

GraphQL
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:

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

Example response payload:

GraphQL
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 securely. You can't view an API key's value after you create it.

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

Ask Community