# Authentication Source: https://docs.graphops.xyz/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](/platform/api-keys#limit-a-key). See [API keys](/platform/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](https://platform.graphops.xyz/organizations/current/api-keys) ## Authentication methods | Method | Endpoint or header | Use it for | | -------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | | Header authentication | `Authorization: Bearer ` | Server-side clients and backends that can attach headers. | | Route-token authentication | `https://subgraphs.graphops.xyz/v1/deploymentCID//` | Query one exact deployment from a client that cannot attach headers. | | Route-token authentication | `https://subgraphs.graphops.xyz/v1/subgraphId//` | Follow a Graph Network Subgraph ID from a client that cannot attach headers. | | Route-token authentication | `https://subgraphs.graphops.xyz/v1/alias//` | 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: `https://subgraphs.graphops.xyz/v1/alias/` and `Authorization: Bearer `. The URL holds no secret. - Route-token authentication: `https://subgraphs.graphops.xyz/v1/alias//`. The URL is the secret. - Full URLs are often copied to: proxy logs, browser history, metrics labels, crash reports. ## Header authentication Send the API key as a bearer token: ```http Authorization: Bearer ``` Example query endpoint: ```text https://subgraphs.graphops.xyz/v1/deploymentCID/ ``` 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: ```text https://subgraphs.graphops.xyz/v1/deploymentCID// https://subgraphs.graphops.xyz/v1/subgraphId// https://subgraphs.graphops.xyz/v1/alias// ``` 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](/platform/api-keys#use-a-key-in-a-browser) 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](./troubleshooting#401-unauthorized). A key limited to other Subgraphs or to other browser origins is refused with `403`; see [Troubleshooting](./troubleshooting#403-forbidden). ## Next steps * [Query your first Subgraph](./getting-started): Send an authenticated query and read the response. * [API integration](./api): Check endpoint shapes, the request envelope, and error responses. * [Identifiers and Endpoint Aliases](./concepts/identifiers-and-aliases): Learn how the key selects your organization's Endpoint Aliases.