Skip to main content
Create one application key per organization, application, and environment. This provides independent access, limits, budgets, attribution, revocation, and migration rollback. Administrative requests use the private operator origin and an admin bearer key.

​
Create a key

In the operator console, open API Keys, select Create key, and choose the public models or aliases the application may use. The form also scopes endpoint access, RPM/TPM, expiry, and an optional budget. The raw token appears once. For automation, call the Admin API:
The response returns key metadata, gateway_url, openai_base_url, and a raw token. The raw token is returned once. Store it immediately in your application secret manager. Creating a key with rpm_limit or tpm_limit requires Redis shared state. A single-process local deployment can instead acknowledge process-local enforcement with shared_state.allow_process_local_throttling: true; without Redis or that explicit acknowledgement, creation returns 409 distributed_rate_limits_required.

​
Fields

​
List keys

The list contains metadata and status, never raw tokens or token hashes.

​
Update a key

In the operator console, open API Keys and select Edit on an active key. Identity fields are read-only; the editable policy includes the display name, model and endpoint scopes, RPM/TPM limits, expiry, and budget. For automation, send only the fields that should change:
budget_usd and budget_duration must be supplied together. Set rpm_limit, tpm_limit, or expires_at to null to clear that limit. Budget enforcement cannot currently be removed from a key; change its amount instead. An update preserves the key ID, raw token, token hashes, tenant/application identity, role, status, budget history, spent amount, reserved amount, and current period dates. No raw token is returned. Changing the duration affects the next period; it does not move the current period deadline. If a budget is reduced below spent_usd + reserved_usd, available budget becomes zero and new reservations fail with budget_exceeded. Existing reservations can still settle, so accounting history remains correct. Raising the limit makes the remaining amount available immediately. The console shows this impact and asks for confirmation before applying a limit below committed usage. Editing a deployment-owned key transfers it to database ownership. Later YAML reloads do not overwrite the edited policy. Key identity fields (id, org_id, app_id, environment, and role) remain immutable; create a replacement key when those fields must change.

​
Rotate a key

Rotation updates the credential in one database transaction and returns the replacement token once:
overlap_seconds defaults to 300 and is bounded from 0 through 86,400. During overlap, current and immediately previous tokens authenticate as the same key with identical tenant, model, endpoint, rate, and budget policy. A later rotation invalidates any earlier generation. Store the new token, update the application secret, verify traffic, and then rotate again with zero overlap or revoke if immediate invalidation is required. Rotation of a deployment-owned bootstrap key transfers ownership to Postgres so YAML reload cannot restore the old token. Raw current/previous hashes and tokens never appear in list or audit responses. previous_token_valid_until reports only the overlap deadline.

​
Revoke a key

Revocation is immediate for both the current token and any overlapping prior token. Blocked keys cannot be edited or unblocked; create a replacement key if access must be restored.

​
Least-privilege recommendations

  • Never share one key across production applications.
  • Grant only the aliases and endpoint paths the application uses.
  • Keep admin keys out of applications and CI logs.
  • Add expiry to temporary and test keys.
  • Set RPM/TPM and budget limits before distributing a production token.