Substreams: Authentication

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.

One API key, two ways to send it. Neither puts the key in the endpoint URL, so a copied or logged URL never exposes it.

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

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:

export SUBSTREAMS_API_KEY="<GRAPHOPS_API_KEY>"

substreams run \
  -e "https://1.evm.substreams.graphops.xyz" \
  "https://github.com/streamingfast/substreams-explorers/releases/download/v1.0.1/ethereum-explorer-v0.1.2.spkg" \
  "map_block_meta" \
  --start-block 18000000 \
  --stop-block +1 \
  -o json

Raw gRPC clients

Attach the key as request metadata on every stream:

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-key headers 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.