# Authentication

Source: https://docs.graphops.xyz/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._

- `SUBSTREAMS_API_KEY`: CLI and sinks
- `x-api-key`: Raw gRPC metadata
- Endpoint: `https://<CHAIN_ID>.evm.substreams.graphops.xyz` (No key in the 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](/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)

## 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

1. Install the Substreams CLI.

2. Set GRAPHOPS\_API\_KEY to your GraphOps API key.

Tested with ethereum-common v0.4.0, substreams 1.25.0.

[Example project](/examples/substreams.authentication.sh-1.tar.gz)

```sh
# 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-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](/substreams/troubleshooting#authentication-fails).

## Next steps

* [Supported networks](/substreams/networks): Copy the endpoint for your network.
* [API integration](/substreams/api): Check the stream fields and messages your client handles.
* [Troubleshooting](/substreams/troubleshooting): Resolve rejected streams and other common failures.