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 principal you attach it to. Create a service account with a Restricted role and exactly the grants it needs, then issue its key. Issuing a key against an Owner and hoping to narrow it afterwards is not something the platform supports.
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 record carries an optional expiry and an optional revocation timestamp. Both are checked before the secret is verified. Most keys have no expiry. Revocation is the control you actually use, and it takes effect on the next request.

​
Two ways to get one

On a service account. The recommended path for anything production. The service account is a principal you can scope with grants, name, audit, and revoke independently of any person. Directly in account settings. Faster, useful for a personal script. The key is bound to your own principal, which means it carries your authority. Both produce the same format and behave identically on the wire. In the Portal: Settings → API Keys, and Settings → Users for service accounts.

​
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. Shared keys cannot be revoked without breaking everything that shares them.
  • Scope the principal, not the key. It is the only scoping that exists.
  • Revoke on suspicion. It is instant and cheap; rotating later is neither.

​
Next steps