API keys and ingest tokens

Osuite uses two kinds of credential, and it is worth keeping them straight because they authenticate different things:

• An ingest token authenticates telemetry arriving at your ingest endpoint. Your OpenTelemetry SDKs and Collectors send it with every batch of traces, logs, and metrics.
• An API key authenticates the Osuite CLI and the AI agents against the Osuite API. It is what the CLI uses to read your telemetry and apply changes on your behalf.

Both are created and managed in the same place: the Osuite UI under Settings → API Keys.

Ingest tokens

An ingest token is the credential your applications and Collectors present when they push OTLP data into Osuite. It travels in the x-osuite-ingest-token header of every request to your regional ingest endpoint:

ingest.<region>.osuite.io:443

You received your first ingest token when your account was created. In snippets throughout these docs it appears as the <your-ingest-token> placeholder. An ingest token grants write access to your account’s telemetry ingestion — it cannot read data or change settings.

API keys

An API key authenticates the Osuite CLI and the AI agents against the Osuite API endpoint:

https://api.<region>.osuite.io

The CLI reads the key from the OSUITE_API_KEY environment variable. Run osuite whoami to confirm a key is valid and to see which account it belongs to. In snippets it appears as the <your-api-key> placeholder. See Set up the Osuite AI agents for how the CLI and agents consume it.

Create a credential

Caution

Treat ingest tokens and API keys as secrets. Do not commit them to source control or paste them into shared documents. Prefer environment variables and a secrets manager over hard-coded values.

1. Open the Osuite UI and go to Settings → API Keys.
2. Create a new ingest token or API key.
3. Copy the value immediately — it is shown once at creation time.

Rotate a credential

Rotate a credential on a schedule and whenever one may have been exposed. Rotation is a create-then-revoke sequence so you never have downtime:

1. Create a new token or key in Settings → API Keys.
2. Update every service, Collector, or CLI environment that used the old value to use the new one.
3. Once nothing is using the old credential, revoke it.

Revoking a credential takes effect immediately: any SDK, Collector, or CLI still presenting the old value will start to fail authentication, so complete step 2 before you revoke.

Where each credential is used

Credential	Sent to	How	Used by
Ingest token	ingest.<region>.osuite.io:443	x-osuite-ingest-token header	OpenTelemetry SDKs and Collectors
API key	https://api.<region>.osuite.io	OSUITE_API_KEY environment variable	Osuite CLI and AI agents

Next steps

• Getting Started — send your first telemetry with an ingest token
• Set up the Osuite AI agents — authenticate the CLI with an API key
• Security and privacy — how ingest tokens are scoped and protected