Subgraphs: Authentication

Authenticate every Subgraph query with an organization-scoped API key, sent either in the Authorization header or in the endpoint path. Use one method per request, and prefer the header when your client can set one.

Create and rotate API keys

Create and rotate API keys in the GraphOps Platform. The platform only shows the plaintext key at creation or rotation time, so store it in your secret manager immediately.

Each query key belongs to one organization and can query the services it includes. Include Subgraphs in the key; one key can also include the other services your application uses. You can also limit a key to specific Managed Subgraphs, Endpoint Aliases, Deployment CIDs, or Graph Network Subgraph IDs; see Limit a key. See API keys for choosing services and rotation.

Use separate keys for production, staging, and local development so you can replace one environment's credentials without affecting the others.

Create or rotate an API key

Authentication methods

Method	Endpoint or header	Use it for
Header authentication	`Authorization: Bearer <GRAPHOPS_API_KEY>`	Server-side clients and backends that can attach headers.
Route-token authentication	`https://subgraphs.graphops.xyz/v1/deploymentCID/<DEPLOYMENT_CID>/<GRAPHOPS_API_KEY>`	Query one exact deployment from a client that cannot attach headers.
Route-token authentication	`https://subgraphs.graphops.xyz/v1/subgraphId/<SUBGRAPH_ID>/<GRAPHOPS_API_KEY>`	Follow a Graph Network Subgraph ID from a client that cannot attach headers.
Route-token authentication	`https://subgraphs.graphops.xyz/v1/alias/<ALIAS>/<GRAPHOPS_API_KEY>`	Query an Endpoint Alias from a client that cannot attach headers.

Prefer header authentication when your client can set headers. Use route-token authentication when a client cannot attach Authorization, such as a hosted dashboard tool that accepts only a URL.

When you query an Endpoint Alias, the API key also selects the organization whose Endpoint Alias namespace is used. An Endpoint Alias name resolves only for keys from the organization that owns it.

With header authentication the key travels only in the Authorization header. With route-token authentication it is part of the URL, and every system that records the URL records the key, so redact the path after the identifier.

Header authentication

Send the API key as a bearer token:

HTTP

Authorization: Bearer <GRAPHOPS_API_KEY>

Example query endpoint:

Reference

https://subgraphs.graphops.xyz/v1/deploymentCID/<DEPLOYMENT_CID>

Use header authentication for server-side HTTPS clients, backend workers, and GraphQL clients that support custom request headers.

Route-token authentication

Put the API key after the Subgraph identifier:

Reference

https://subgraphs.graphops.xyz/v1/deploymentCID/<DEPLOYMENT_CID>/<GRAPHOPS_API_KEY>
https://subgraphs.graphops.xyz/v1/subgraphId/<SUBGRAPH_ID>/<GRAPHOPS_API_KEY>
https://subgraphs.graphops.xyz/v1/alias/<ALIAS>/<GRAPHOPS_API_KEY>

Use route-token authentication for clients that cannot attach custom headers. Do not send the same API key in both the URL and the Authorization header.

Treat route-token URLs as secrets

Route-token authentication puts the API key in the URL. URLs can appear in application logs, reverse-proxy logs, browser history, crash reports, metrics labels, and support screenshots. Redact the path after the Deployment CID, Graph Network Subgraph ID, or Endpoint Alias, and rotate the key if a route-token URL is exposed.

Security guidance

Store API keys in a server-side secret manager when possible.
Keep organization API keys out of public frontend bundles and send requests through your backend, unless you use a browser key whose services are each limited to your website's origins and to the targets your frontend queries.
Use separate keys per environment. A route-token URL exposes the key to anyone who can read it.
Redact API keys from URLs before logging request paths, errors, or metrics.
Rotate keys from the platform when a key or route-token URL is exposed.

Fix `401 Unauthorized`

A 401 means the key is missing, malformed, or no longer valid, or is a service account API key rather than a query key. Work through the checks in Troubleshooting. A key limited to other Subgraphs or to other browser origins is refused with 403; see Troubleshooting.

Create and rotate API keysCopy Anchor Link

Authentication methodsCopy Anchor Link

Header authenticationCopy Anchor Link

Route-token authenticationCopy Anchor Link

Security guidanceCopy Anchor Link

Fix 401 UnauthorizedCopy Anchor Link

Next stepsCopy Anchor Link