Revoking a key
DELETE /v1/api-keys/{id}
Required scope: tenant:admin
Use the key’s id (the UUID from GET /v1/api-keys), not its prefix and not
its secret.
It takes effect on the next request
Revocation sets revoked_at on the row. Authentication reads that on every
request, so a revoked key stops working immediately. There is no cache to
expire and no propagation delay.
A revoked key is explicit about its state rather than pretending it never existed:
{
"type": "about:blank",
"status": 401,
"title": "Revoked API key",
"detail": "This key was revoked on 2026-10-17T09:41:02Z"
}
That title is different from Invalid API key, which is useful: it tells
you a deployment is holding a key you retired, rather than one that was never
right.
The row stays
Revoking does not delete anything. The key keeps its id, prefix, label,
scopes and last_used_at, and still appears in GET /v1/api-keys with
revoked_at set.
That is deliberate. After an incident the question is usually “what could this key reach, and when was it last used”, and deleting the row would throw away both answers.
You cannot revoke the key you are using
This has a practical consequence for automation: a script cannot clean up
after itself. If you are rotating programmatically, the new key revokes the
old one, which means the new key needs tenant:admin too, and that is a good
reason to do rotation from the console instead. See
Rotating keys.
When to revoke
Immediately, for anything you suspect:
- a key that appeared in a commit, a log, a screenshot or a support thread
- a key held by a service you have decommissioned
- a key belonging to someone who has left
- any key you cannot account for
And routinely, for anything with a stale last_used_at. A key nothing has used
for months is pure exposure: it can still do everything it ever could, and
nobody will notice when it is used.
Revoking is cheap and reversible in the only sense that matters: you cannot un-revoke, but you can always issue a new key. There is no reason to hesitate over a suspicious one.
What revocation does not do
It does not stop mail already queued. A send accepted before revocation still goes out: the key authorised the request at the time, and the message is no longer associated with it.
To stop a message that has not gone yet, cancel the message itself with
DELETE /v1/messages/{id}, which works while a scheduled send is still
pending. Revoking the key it was sent with does nothing to it.