Skip to main content
Every request needs an API key in the Authorization header. Keys belong to a project inside your workspace.

​
Key format

​
Live and test keys

Use test keys in CI and while you build.

​
Scopes

Every scope is read-only. A request outside the key’s scopes returns 403 insufficient_scope and costs nothing.

​
Presets

Read only grants the same access as All, since every scope is read-only. You can change a key’s scopes later in the console. Widening them requires your second factor if two-factor sign-in is on.

​
Per-key limits

Agent keys carry their own limits on top of the plan. Other keys use the plan limits only, since the console cannot set limits on them.
  • Rate limit: requests per second, with a burst of twice that. Exceeding it returns 429 rate_limited.
  • Credit budget: credits per UTC day. Exceeding it returns 403 credits_exhausted.
  • Per-request maximum: a request whose maximum cost is higher is refused with 403 max_credits_exceeded before it runs.
  • IP allowlist (any key): a list of CIDR ranges. Requests from other addresses return 403 ip_not_allowed. A workspace policy can require an allowlist on every key.

​
Expiry, rotation, and revocation

  • Expiry: 30, 90 (default), or 120 days, capped by the workspace maximum. Keys that never expire are available only if a workspace admin allows them and no maximum is set. An expired key returns 401 expired_key.
  • Rotation: Rotate issues a replacement with the same scopes, allowlist, and limits. The old key keeps working for an overlap you choose: none, 1 hour, 24 hours (default), or 7 days, but never past its own expiry. Revoked and expired keys can’t be rotated.
  • Revocation: takes effect within about 5 seconds. A revoked key returns 401 revoked_key and stays listed in the console for audit.
Keep keys on your server. Never ship a key in a browser bundle, mobile app, or public repository: anyone holding it can spend your credits. Browser apps should call your backend, and your backend calls us.