API key management

Getting started → API keys walks through creating a key. This page is the operator reference: every option a virtual key can carry, when to use it, and how to retire keys safely.

Anatomy of a virtual key

A virtual key is a token with metadata attached. The token authenticates the request; the metadata controls what that request is allowed to do.

The metadata you can attach:

name: Human label, shown in usage history.
models: Allowlist of model IDs. Empty = all models.
region: Pin requests through this key to a region (e.g. eu-west).
daily_credit_limit: Max credits this key can spend per UTC day.
monthly_credit_limit: Max credits per UTC calendar month.
expires_at: Optional auto-expiry timestamp.
prefer_low_carbon: When set, biases auto-routing on this key toward lower-grid-intensity providers.
enabled: Toggle without deleting.

All of these can be edited from Dashboard → Keys → key name → Edit. Edits take effect on the next request, no caching delay.

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 is allowlisted to the models that environment actually uses.

One key per third-party integration. If you give a token to a desktop client (ChatBox, Cline, Claude Code, …), put it in its own key with a daily limit. The blast radius of a leaked key is then “yesterday’s daily limit” instead of “everything.”

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 region requirement. When a particular workload must stay in eu-west, set the region on the key rather than on every request. The constraint travels with the key and a misconfigured client can’t accidentally send the request elsewhere.

Limits and what happens when they’re hit

When a request would push a key over its daily_credit_limit or monthly_credit_limit, the gateway returns 429 Too Many Requests with an explanatory body:

JSON

{
  "error": {
    "type": "rate_limited",
    "code": "key_daily_limit_exceeded",
    "message": "API key 'prod-api' has reached its daily credit limit (5.00).",
    "param": null
  }
}

The response includes Retry-After indicating when the limit resets (midnight UTC). Bumping a limit takes effect immediately for subsequent requests.

Rotation

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

Create a second key with the same scope.
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.

Audit trail

Every key creation, edit, rotation, and revocation produces an entry in Settings → Audit log. The log records: who acted, when, on which key, and what changed. Export as CSV for retention in your own audit pipeline.