Revoke an API key
Revoke an API key.
Revoke an API key.
Requires the keys:write scope. The key is DEACTIVATED
rather than deleted: status becomes inactive and authentication
refuses it within 30 seconds, but an account admin can still undo a
mistake.
The endpoint refuses to revoke the key making the request, so an integration cannot lock itself out mid-call.
Only keys belonging to the caller's own organization can be selected, so a key id obtained elsewhere cannot reach another tenant's key. A key id that does not exist in this organization returns 404, never 403 — the existence of another tenant's key is not something this API confirms.
Revoking an already-inactive key is a no-op that returns its existing revocation timestamp, so a retried request is safe.
Errors: 401, 403 (missing scope or wrong organization), 404 (no such key in this organization), 409 (another key change is still being applied — retry — or the caller tried to revoke its own key), 429, 503.
Rate limit: 2000 requests per minute per organization, counted together with every endpoint that has no stricter limit of its own. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.
v2/api-keys/{key_id}Authorization
AuthorizationRequiredBearer <token>
Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.
In: header
Path Parameters
key_idRequiredKey Id
The 'key_...' id from GET /v2/api-keys.
Query Parameters
organization_idOrganization Id
Optional; must match the key's organization.
Response Body
200
The key's new state. Revocation is a deactivation, not an erasure.
key_idRequiredKey Id
The key that was revoked.
statusRequiredStatus
Always 'inactive' once revoked.
revokedRequiredRevoked
Always true; a failure is reported as an error envelope.
revoked_atRevoked At | null
When the revocation was recorded.
401
1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of an API key.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
403
1102 — the key is valid but lacks the scope this endpoint requires, or names another organization. GET /v2/scopes reports what a key holds.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
404
1200 — no such resource in your organization. A resource belonging to another organization answers 404, never 403.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
409
1201 — the resource's current state does not allow this action.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
422
1001 — the body or query failed validation; the message names the first offending field.
errorRequiredinteger
Stable integer code from the error table. Branch on this, not on the message.
messageRequiredstring
One human-readable sentence. Wording may change; the code will not.
429
1300 — the per-organization request rate or concurrent-call limit was reached. Carries Retry-After.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
503
1501 — a service this endpoint depends on is unreachable or returned a 5xx.
errorRequiredError
Stable integer code from the /v2 error table. Branch on this.
messageRequiredMessage
One human-readable sentence. Wording may change; the code will not.
The key's new state. Revocation is a deactivation, not an erasure.