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 API keys 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 query key belongs to one organization and can query the services it includes. Include Substreams in the key; one key can also include the other services your application uses. You can also limit a key's Substreams access to the networks you stream from; 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(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 API keys in the endpoint URL. |
| Query-string API key | No | Do not put 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.
CLI · 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 \
-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.
Next steps
Last updated