API key management

Getting started → API keys walks through creating a key. This page is the operator reference: every option an API key carries today, how to retire keys safely, and what is on the way.

Anatomy of an API key

An API key is a token with metadata attached. The token authenticates the request; the metadata describes the key and shapes how its requests are routed.

The metadata a key carries today:

name: Human label, shown in usage history and on the Activity page’s per-key filter.
expires_at: Auto-expiry timestamp, set from a preset at creation (30 days / 90 days / 6 months / 12 months / never; default 90 days). Past it, the key returns 401 api_key_expired and its secret is purged at rest.
routing_profile_id: A routing profile applied to this key’s auto/ requests instead of the account default.

name and routing_profile_id can be edited from the Keys page: open the key and choose Edit. Edits take effect on the next request, with no caching delay. expires_at is fixed at creation; to change a key’s lifetime, create a new key and rotate.

The update endpoint accepts exactly these fields. Any other field in the body is rejected with 400 invalid_request_error naming it, so a setting that does not exist yet can never appear to have been saved.

Scoping patterns

A few patterns we see often:

One key per environment per service. The most common shape: prod-api, staging-api, local-dev. Each one’s spend and request history stays separate on the dashboard, and revoking one leaves the others untouched.

One key per third-party integration. If you give a token to a desktop client (ChatBox, Cline, an IDE agent, …), put it in its own key. If that client leaks the key, you revoke one key and nothing else stops working, and its usage history tells you exactly what the leaked key did.

One key per researcher / experiment. When the same project runs multiple lines of experiments, separate keys make the dashboard’s top-models chart instantly readable per experiment.

One key per routing profile. When a particular workload needs its own auto/ policy (a carbon ceiling, a jurisdiction gate, a provider preference), attach the profile to the key rather than configuring every client. The policy travels with the key.

Coming soon: per-key controls

The next round of key metadata will let a key carry its own limits, so that the blast radius of a leaked or runaway key is bounded by the key itself rather than by your whole balance. Planned fields:

models: an allowlist of model IDs the key may call.
region: pin every request through the key to one region.
daily_credit_limit and monthly_credit_limit: a spend ceiling per UTC day and per UTC calendar month, after which the key’s requests will be refused with a 429 until the window resets.
enabled: pause a key without deleting it.

None of these are live yet. Until they ship, a key has the whole account balance available to it, and the way to bound exposure is the scoping above plus revocation. Sending any of these fields today returns 400 rather than being accepted and ignored. This page will document the exact request shape and error payloads when they ship.

Rotation

The rotation pattern that does not require zero-downtime support from the gateway:

Create a second key with the same name pattern and routing profile.
Deploy it everywhere the old key was used (config, secret manager, CI variables).
Verify the new key is in use by watching the usage history; the old key’s request rate should drop to zero.
Delete the old key.

Aim to rotate at least every 90 days, and immediately after any of the events listed in Getting started → API keys.

Revocation

A revoked key returns 401 Unauthorized on the next request. There is no warning, no grace period, no caching delay. Revocation cannot be undone. If you revoke the wrong key, create a new one.

The dashboard preserves the key’s usage history after revocation. The token itself is discarded.