# Authentication Source: https://docs.graphops.xyz/rpc/authentication Choose how your clients send their API key, and keep that key out of places it can leak. GraphOps RPC accepts an organization-scoped API key either in the `Authorization` header or in the endpoint path. Use one authentication method per request. ## 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 RPC in the key; one key can also include the other services your application uses. You can also limit a key's RPC access to the networks your application calls; 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 ` | HTTPS requests and server-side clients that can attach headers. | | Route-token authentication | `https://rpc.graphops.xyz/v1/evm//` | HTTPS clients that cannot attach custom headers. | | Route-token authentication | `wss://rpc.graphops.xyz/v1/evm//` | WebSocket clients, including browser-native WebSocket clients. | | Route-token authentication | `https://rpc.graphops.xyz/v1/bitcoin//` | Bitcoin HTTPS clients that cannot attach custom headers. | Prefer header authentication when your client can set headers. Use route-token authentication when a client cannot attach `Authorization` during the connection, especially for WebSocket handshakes. *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 chain ID or network name.* - Header authentication: `https://rpc.graphops.xyz/v1/evm/1` and `Authorization: Bearer `. The URL holds no secret. - Route-token authentication: `wss://rpc.graphops.xyz/v1/evm/1/`. 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 HTTPS endpoint: ```text https://rpc.graphops.xyz/v1/evm/1 ``` Use header authentication for server-side HTTPS clients, backend workers, and libraries that support custom request headers. ## Route-token authentication ### EVM route-token endpoints Put the API key after the chain ID: ```text https://rpc.graphops.xyz/v1/evm// wss://rpc.graphops.xyz/v1/evm// ``` For Ethereum mainnet, the route-token endpoints are: ```text https://rpc.graphops.xyz/v1/evm/1/ wss://rpc.graphops.xyz/v1/evm/1/ ``` ### Bitcoin route-token endpoints Put the API key after a network name from [Supported networks](./networks): ```text https://rpc.graphops.xyz/v1/bitcoin// https://rpc.graphops.xyz/v1/bitcoin/mainnet/ ``` Use route-token authentication for WebSocket clients and HTTPS 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 chain ID for EVM endpoints or after the network name for Bitcoin endpoints, and > rotate the key if a route-token URL is exposed. ## WebSocket authentication Route-token authentication is the recommended WebSocket pattern because many WebSocket clients cannot send custom `Authorization` headers during the handshake. Prerequisites 1. Install Node.js. 2. Install tsx and ws. `npm install tsx ws` 3. Set GRAPHOPS\_API\_KEY to your GraphOps API key. Tested with Node.js 24.22.1, tsx 4.23.15, ws 8.22.0. [Example project](/examples/rpc.authentication.ts-6.tar.gz) ```typescript import WebSocket from "ws"; // Route-token URL: the API key is the final path segment. const socket = new WebSocket( `wss://rpc.graphops.xyz/v1/evm/1/${process.env.GRAPHOPS_API_KEY}`, ); socket.once("error", (error) => { throw error; }); socket.once("open", () => { console.log(JSON.stringify({ connected: true })); socket.close(); }); ``` If your server-side WebSocket client supports custom headers, header authentication is also valid: Prerequisites 1. Install Node.js. 2. Install tsx and ws. `npm install tsx ws` 3. Set GRAPHOPS\_API\_KEY to your GraphOps API key. Tested with Node.js 24.22.1, tsx 4.23.15, ws 8.22.0. [Example project](/examples/rpc.authentication.ts-7.tar.gz) ```typescript import WebSocket from "ws"; const socket = new WebSocket("wss://rpc.graphops.xyz/v1/evm/1", { headers: { Authorization: `Bearer ${process.env.GRAPHOPS_API_KEY}`, }, }); socket.once("error", (error) => { throw error; }); socket.once("open", () => { console.log(JSON.stringify({ connected: true })); socket.close(); }); ``` ## 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, WebSocket URLs, errors, or metrics. * Rotate keys from the platform when a key or route-token URL is exposed. ## Next steps * [Troubleshooting](./troubleshooting#401-unauthorized): Work through the checks for a `401 Unauthorized` response. * [WebSocket subscriptions](./guides/websocket-subscriptions): Subscribe to live logs with a route-token endpoint. * [Supported networks](./networks): Copy the endpoint and chain ID for your network.