Ingest keys

An ingest key is the credential an agent sends with its telemetry. It tells Scout Trails which actor, and so which organization, the telemetry belongs to. Each actor holds at most one ingest key at a time.

An ingest key can only send telemetry. It cannot read anything: the API and MCP reject it with 401. To read data programmatically, use an API key.

Key format

An ingest key is a random 43-character string of letters, digits, - and _, with no prefix. For example:

4qJx0bZ7mN2pL9sT1vW8yC3dF6gH5kR0aE-uI_oPq2s

Where to find a key

Every member can see every actor’s current key. Open Manage → Actors & ingest keys; the Ingest key column of the All actors table shows each actor’s key, or none when it has no key.

The key stays on this page for as long as it is valid, so you can come back and copy it again at any time. Because every member can see every key, treat the Manage area as sensitive and remove people who no longer need access. See Removing a member.

Copying a key

Select Copy next to the key, either in the All actors table or in the dialog shown after a key is issued. The button briefly reads “Copied”. If it reads “Copy failed”, your browser blocked clipboard access; select the key text and copy it manually.

Using a key

Send the key as a Bearer token in the OTLP Authorization header, over gRPC. For Claude Code that means:

export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.scoutmonitoring.io:443
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your-ingest-key>"

Keep the quotes around the header value: the space after Bearer breaks the unquoted form. Codex CLI sets the same header in ~/.codex/config.toml. Full per-agent setup is in Claude Code and Codex CLI.

When keys take effect

Scout Trails checks the key on every export, with no caching:

• A newly issued key works immediately.
• A revoked, rotated-out or deactivated actor’s key stops working immediately.

The ingest endpoint rejects a request with gRPC status PERMISSION_DENIED when the Authorization header is missing, does not use the Bearer scheme, is empty, or carries a key that does not belong to an active actor. Agents treat this as final and do not retry, so telemetry sent with a key that no longer works is not recorded.

Issuing a key

An actor gets its first key automatically when you create it. To give a key to an actor whose key was revoked:

1. Open Manage → Actors & ingest keys.
2. On the actor’s row, select Issue key.
3. Copy the key from the Ingest key issued for name dialog and select Done.

Rotating a key

Rotating replaces an actor’s key with a new one. The actor, its telemetry id and all its past telemetry stay the same, so the actor’s history continues unbroken under the new key.

1. Open Manage → Actors & ingest keys.
2. On the actor’s row, select Rotate key.
3. Copy the new key from the Ingest key issued for name dialog.
4. Replace the old key in the agent’s configuration and restart the agent.

The banner confirms “New ingest key issued for name. The previous key stopped working immediately.” An actor has only one key, so there is no overlap period: anything the agent sends between step 2 and step 4 is rejected. Do steps 2 to 4 together, while the agent is idle.

Revoking a key

Revoking removes an actor’s key without issuing a new one. The actor stays on the page with key none and can be given a new key later with Issue key.

1. Open Manage → Actors & ingest keys.
2. On the actor’s row, select Revoke key.

The banner confirms “name can no longer send telemetry.” Past telemetry is unchanged.

To retire an actor completely instead, use Deactivate. See Revoke key, Rotate key and Deactivate.

Messages you can see

Related pages

• Actors
• Agent instrumentation
• API keys