Key security

Where to keep a key

Server-side only. A key that ends up in a browser bundle, a mobile app or a public repository should be treated as compromised — even with private source, the build ships to the user. If your frontend needs the API, proxy requests through your own backend so the key never leaves your perimeter.

Scopes

A key can be restricted to the chat, images and videos surfaces — a service that only generates images has no business calling chat. A request to a surface outside the key’s scopes returns a 403 permission_error with code insufficient_scope. A key with no scopes selected can reach every surface.

Spending caps instead of IP allowlists

We do not support IP allowlists: they break on any dynamic infrastructure and give a false sense of safety — a stolen key still works from an allowed host. Instead, each key can carry its own spending cap over a period and its own requests-per-minute limit.

• A spending cap over a day · week · month · total. Once exhausted, requests get a 402 spend_limit_exceeded.
• Its own requests-per-minute limit, independent of the account default.

Details are in Limits & credits. In practice: one key per service and environment, each with its own cap.

Rotation and revocation

The full secret is shown once, at creation. To rotate a key, issue a new one, switch your service over, and only then revoke the old one — that way there is no window of failure. Revocation takes effect immediately: key lookups are cached for a minute, but revoking busts that cache explicitly.

{
  "error": {
    "message": "API key lacks scope: images",
    "type": "permission_error",
    "param": null,
    "code": "insufficient_scope"
  }
}