Authenticate every Substreams stream with an organization API key. The Substreams CLI and sinks
read the key from the SUBSTREAMS_API_KEY environment variable; raw gRPC clients send it in the
x-api-key request metadata. The key never goes in the endpoint URL.
Create and rotate API keys
Create a Substreams API key in the platform. The platform shows the plaintext key only when you create or rotate it, 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 Substreams key(opens in a new tab)Send the key
| Pattern | Supported | Use it for |
|---|---|---|
SUBSTREAMS_API_KEY | Yes | The Substreams CLI, including substreams sink commands. |
x-api-key: <GRAPHOPS_API_KEY> | Yes | Raw gRPC clients that attach request metadata. |
| Route-token URL | No | Do not put Substreams API keys in the endpoint URL. |
| Query-string API key | No | Do not put Substreams API keys in query parameters. |
| mTLS | No | Use x-api-key authentication unless your enterprise contract states otherwise. |
Substreams CLI
Export the key, then run any substreams command against a GraphOps endpoint:
Prerequisites
Install the Substreams CLI.
Set GRAPHOPS_API_KEY to your GraphOps API key.
Substreams CLI
# The CLI sends SUBSTREAMS_API_KEY to GraphOps in the x-api-key header.
export SUBSTREAMS_API_KEY="${GRAPHOPS_API_KEY}"
# Stream USDC Transfer events (--params) for block 18000002 as JSON lines.
substreams run \
-e "https://1.evm.substreams.graphops.xyz" \
"https://spkg.io/v1/packages/ethereum-common/v0.4.0" \
"filtered_events" \
--params "filtered_events=evt_addr:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 && evt_sig:0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef" \
--start-block 18000002 \
--stop-block +1 \
--max-retries 0 \
--force-protocol-version 2 \
-o jsonl
Raw gRPC clients
Attach the key as request metadata on every stream:
HTTP
x-api-key: <GRAPHOPS_API_KEY>
Protect the key
- Store API keys in a server-side secret manager.
- Do not commit API keys to Substreams manifests, sink configs, shell history, or source code.
- Redact
x-api-keyheaders from logs, metrics, traces, and support output. - Use separate keys per environment and rotate a key as soon as it is exposed.
- Revoke or replace keys in API keys. Ask an Owner or Developer if you lack permission.
If a stream is rejected, follow the checks in Authentication fails.