API Keys

API keys are managed in the dashboard (API Keys) by organization members with the owner, admin or developer role. This page covers the concepts; the request-level mechanics are on Authentication.

Anatomy of a key

Property	Description
`name`	Label you choose (≤ 120 chars).
`prefix`	First 12 characters of the secret (`sk-llm-a1b2c`), shown in lists so you can identify a key without the secret.
`status`	`active`, `disabled` or `revoked`.
`project_id`	Optional project grouping within the organization.
`expires_at`	Optional hard expiry.
`last_used_at`	Updated as the key is used — handy for finding stale keys.
`rotated_from_id`	Set on keys created by rotation.
`spend_today_micro` / `spend_month_micro`	Live spend counters (UTC day / calendar month) in micro-USD.

The secret itself is never stored — only its SHA-256 hash — and is displayed once at creation or rotation.

Limits you can set per key

Limit	Range	Enforced as
`allowed_models`	up to 500 model ids	`403 model_not_allowed`
`allowed_modalities`	subset of `text`, `image`, `audio`, `video`, `music`, `embedding`	`403 modality_not_allowed`
`allowed_ips`	up to 200 IPv4/IPv6 addresses or CIDRs	`403 ip_not_allowed`
`rate_limit_rps`	1 – 100,000	`429 rate_limited`
`rate_limit_rpm`	1 – 10,000,000	`429 rate_limited`
`tokens_per_minute`	≥ 1	`429 tokens_per_minute_exceeded`
`concurrent_requests`	1 – 10,000	`429 concurrency_exceeded`
`budget_daily_micro`	≥ 0 micro-USD	`402 budget_exceeded`
`budget_monthly_micro`	≥ 0 micro-USD	`402 budget_exceeded`
`expires_at`	ISO-8601 timestamp	`401 key_expired`

Unset limits are unlimited at the key level; organization limits still apply. The organization also has a maximum number of keys (creating beyond it fails in the dashboard with max_api_keys_reached).

Budgets and how they are checked

Budgets and balance are checked before each request against the estimated cost (see Pricing), and adjusted to the actual cost afterwards. The check order is:

Organization credit balance (insufficient_credits)
Key daily budget, then key monthly budget (budget_exceeded)
Organization monthly spending limit (spending_limit_exceeded)
Operator quotas

Daily and monthly windows are UTC calendar periods. A budget is exceeded when spent_so_far + estimate > budget, so a large request may be refused even if a smaller one would pass.

402 vs 429

	`402 Payment Required`	`429 Too Many Requests`
Type	`quota_error`	`rate_limit_error`
Codes	`insufficient_credits`, `budget_exceeded`, `spending_limit_exceeded`	`rate_limited`, `tokens_per_minute_exceeded`, `concurrency_exceeded`, `provider_rate_limited`
Meaning	You (or this key) cannot afford the request right now.	You are sending too fast.
Fix	Top up credits, raise the key budget or organization limit, or wait for the daily/monthly window to reset.	Wait `Retry-After` seconds and retry; lower concurrency.
Retrying helps?	No (until money or window changes).	Yes.
Charged?	No.	No.

json

{
  "error": {
    "type": "quota_error",
    "code": "budget_exceeded",
    "message": "Daily budget of 5.000000 USD for this API key would be exceeded",
    "request_id": "req_01J6ZK3M9PQR7S8T9V"
  }
}

Lifecycle operations

Action	Effect
Create	Returns the secret once.
Edit	Change name, limits, scopes, status (`active` ⇄ `disabled`). Takes effect within seconds.
Rotate	Issues a new secret with the same settings; the old key becomes `revoked` immediately.
Revoke	Permanently disables the key.
Delete	Removes a revoked key from the list.
Usage	Per-key usage (requests, tokens, spend, errors) over time is available in the dashboard.

Recommendations

One key per service and environment; put the environment in the name.
Restrict allowed_models and allowed_modalities to what the service needs — a leaked chat key should not be able to generate video.
Set budget_monthly_micro on every key; set budget_daily_micro on keys used by public-facing features.
Pin server keys to egress IPs with allowed_ips.
Prefer rotation over long-lived secrets; schedule it.
Never ship a key to a browser or mobile app — proxy through your backend.