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 Subgraphs 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 key belongs to one organization and product. Use separate keys for production, staging, and local development so you can replace one environment's credentials without affecting the others.

Create or rotate a Subgraphs 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	`/v1/deploymentCID/<DEPLOYMENT_CID>/<GRAPHOPS_API_KEY>`	Clients that cannot attach custom headers.
Route-token authentication	`/v1/subgraphId/<SUBGRAPH_ID>/<GRAPHOPS_API_KEY>`	Graph Network Subgraph ID endpoints without headers.
Route-token authentication	`/v1/alias/<ALIAS>/<GRAPHOPS_API_KEY>`	Query an Endpoint Alias without headers.

Prefer header authentication when your client can set headers. Use route-token authentication when a client cannot attach headers. When querying an Endpoint Alias, the authenticated API key determines which organization's Endpoint Alias namespace is used.

Header authentication

Send the API key as a bearer token:

Authorization: Bearer <GRAPHOPS_API_KEY>

Example query endpoint:

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

Route-token authentication

Put the API key after the Subgraph identifier:

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>

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 segment that contains the API key, 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; send requests through your backend.
Prefer separate, environment-specific keys for production, staging, and local development.
Redact API keys from URLs before logging request paths, errors, metrics, or support output.
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. Work through the checks in Troubleshooting.