Skip to main content
An API key is a long-lived bearer credential for unattended callers: backend services, integrations, scheduled jobs. Unlike a session or a device-flow token, it does not expire on its own.

​
Format

  • ak- marks the string as an API key.
  • Access id — 32 hex characters, a UUID with the hyphens stripped. This is the public half; it is how the key is looked up.
  • Secret — appended directly after, no separator. This is the half that is verified.
An older form with a dot between the two halves is still accepted. The secret is stored as a hash. It is shown once at creation and cannot be recovered.

​
Sending one

The management API accepts an API key four ways:
Authorization: Bearer is tried as a JWT first, then falls back to API-key validation — but prefer one of the explicit forms above. MCP gateways and the agent gateway both accept an API key as a bearer credential, disambiguated by the ak- prefix.

​
Where a key’s authority comes from

This is the part worth internalizing. An API key carries no permissions of its own. It identifies a principal, and that principal’s role and grants decide what the request may do. The practical consequence: you scope a key by scoping the service account you mint it on. A service account is Restricted — it authorizes nothing until you grant it something. Give it exactly the grants it needs, then mint its key. Narrowing later means changing that principal’s grants; there is no per-key control to reach for.
There is no per-key permission list, no per-key resource scope, and no per-key rate limit. A rate_limit column exists on the key record but nothing reads it. Do not design around it.

​
Lifecycle

A key is live from the moment it is created until you delete it. There is no expiry to set, so a key does not age out on its own — deleting it is the control. Deleting takes effect on the next request: the record is removed, and anything still presenting that key stops authenticating.

​
Getting one

Every key belongs to a service account — a named principal you scope with grants, and can audit and delete independently of any person. There is no personal key bound to your own sign-in identity. In the Portal: Settings → API Keys. Create the service account there, then mint a key on it. Settings → Users is the roster of the humans on your account; no key is issued from it.

​
API key or device flow?

Use a key when nobody is at the keyboard. Use the device flow when a person is, and their identity should be on the record.

​
Practical guidance

  • Environment variables or a secret manager. Never version control, never a config file you commit.
  • One key per consumer. A shared key cannot be deleted without breaking everything that shares it.
  • Scope the principal, not the key. It is the only scoping that exists.
  • Delete on suspicion. It is instant and cheap; rotating later is neither.

​
Next steps