API keys
Minting a key, the single disclosure, the scopes that decide what it reaches, and how to revoke one.
An API key lets a program call the API without a person signing in. Keys live at Settings, API keys. Every key operation is admin only.
Two things about keys matter more than everything else on this page, so they come first.
The two rules
A key with no scopes reaches nothing. Scopes are what a key may do, and the default is an empty set. An unscoped key is refused at every operation.
The secret is shown exactly once. It appears in the response that creates the key and nowhere else, ever. Nothing can recover it. A lost secret means minting a replacement and revoking the old key.
Scopes
A scope is <tag>:read, <tag>:write, <tag>:*, or * for everything.
The tag is the group an operation belongs to in the
API reference. So tickets:read covers the ticket reads, and
tickets:write covers the ticket writes and the reads with them, because a
caller allowed to change something is allowed to see it.
* is an explicit grant of everything, and it is the only scope that covers
operations added after the key was minted. Every other scope names a tag, so a
key reaches a new operation only if its scopes already name that operation's
group. A key that names no scope covering an operation is refused, always.
There is no default that lets anything through.
Scopes are checked when the key is created, against what this deployment can
actually grant. A value like tickets:delete, which no operation could ever
require, is refused at creation rather than stored as a key that fails everywhere
for a reason nobody can see.
Scopes narrow, they never widen
A key acts as the admin who created it. It cannot do more than that person's current workspace role allows, and the role is read live on every request. So:
- Demoting the owner demotes every key they issued.
- Removing them from the workspace kills those keys.
Neither needs any key administration. See Members and roles.
A key is also minted into the workspace the create call was made against and is bound to it. It cannot be pointed at another workspace.
Pinning to one agent
agent_id on create adds an agent:<uuid> scope. It names a resource and no
action, so it grants nothing on its own. It narrows a key that also carries
action scopes.
Minting a key
POST /v1/api-keys takes a name, an optional scopes list, an optional
agent_id and an optional expires_in_days.
Read the secret out of the response and store it before you close the
connection. That is the one disclosure.
Mint keys with scopes through the API
The Studio dialog collects a name, an optional agent and an optional expiry. It
does not collect scopes, so a key created there is minted with an empty scope set
and reaches nothing. The key list also shows an empty scope set as
"workspace-wide", which describes an older behaviour rather than the current one.
To mint a key that can actually do something, call POST /v1/api-keys and send
scopes.
Set an expiry
expires_in_days is optional, and leaving it out means the key never expires on
its own.
Set one. An expiry is the only thing that limits a leaked secret without somebody noticing and revoking it.
Using a key
Present it as a bearer token:
Authorization: Bearer sk_zr_...That is the same header a signed-in user's access token travels on. The sk_zr_
prefix is what tells the two apart, so a caller chooses a credential, never a
header.
The two credential types are not interchangeable in what they reach. See Authentication in the API reference.
The key list
The list is the inventory: what exists, what each key may reach, and whether anybody is still using it. It never returns a secret.
| Column | What it tells you |
|---|---|
| Name | Whatever you called it. |
| Prefix | The readable head of the secret, the only part stored in the clear. Use it to match a key here against one pasted into a deployment. |
| Scopes | The whole of what this key may reach. An empty list reaches nothing. |
| Last used | Null for a key that has never authenticated a request, which is how a misconfigured or forgotten key is spotted. |
| Expires | Null means it never expires on its own. |
Revoked keys are hidden unless you ask for them.
Revoking a key
This is the half that matters when something has gone wrong.
POST /v1/api-keys/{key_id}/revoke, or the revoke control on the key list, stops
a key working from the next request. There is no grace period and no token
lifetime to wait out.
The row stays, so the key keeps its name, its prefix and its last-used time for whoever asks later what it was and who minted it.
Revocation is one way. A revoked key cannot be brought back, and the replacement is a new key with a new secret.
Revoking a key that is already revoked answers 404, the same as a key id that is not in this workspace. That is deliberate: a 200 from this route is proof the key is now dead, not merely proof that you addressed it.
Deleting a key
DELETE /v1/api-keys/{key_id} removes the row entirely.
Prefer revoking. A delete stops the key just as completely and also destroys the record of what it was and who minted it, which is exactly what somebody reviewing a past incident needs.
A 204 always means a key was really removed. Deleting a key id that is not in this workspace, or one already gone, answers 404.
What is recorded
Creating, revoking and deleting a key are all written to the audit log, with the key's name, prefix and scopes. See The audit log.