Revoke an API key · Ownrecord docs

Revokes an API key. It stops working immediately: every later request with it fails with api_key_invalid. Revocation is permanent; create a new key to replace it. Revoking a key that is already revoked changes nothing and returns it (the original revokedAt stays).

At a glance

REST: POST /api/v1/api_keys/{id}/revoke
MCP tool: api_keys_revoke
Operation ID: api_keys.revoke
Scope: Organization, or one of its legal entities or brands
Permission: keys:admin
Risk tier: security
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key required
Modes: Test and live
Authentication: API key with the keys:admin scope
Since: M1

Request

Path parameters

Field	Type	Description
`id`	`key_…` ID

Body

This operation takes no body.

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`key_…` ID
`object`	`"api_key"`
`kind`	one of `org`, `entity`, `brand`
`livemode`	boolean
`name`	string
`prefix`	string
`scopes`	array of one of 98 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document)
`status`	one of `active`, `expired`, `revoked`
`orgId`	`org_…` ID
`entityId`	`ent_…` ID or null
`brandId`	`brd_…` ID or null
`createdBy`	string
`createdAt`	date-time
`updatedAt`	date-time
`expiresAt`	date-time or null
`lastUsedAt`	date-time or null
`revokedAt`	date-time or null

Examples

Revoke a leaked key

HTTP

POST /api/v1/api_keys/key_01m4ttwd3tesktp0hc6bpxwkpd/revoke
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14

Response (200):

JSON

{
  "id": "key_01m4ttwd3tesktp0hc6bpxwkpd",
  "object": "api_key",
  "kind": "brand",
  "livemode": false,
  "name": "Billing backend",
  "prefix": "or_test_acme",
  "scopes": ["customers:write", "subscriptions:write", "usage:write"],
  "status": "revoked",
  "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "brandId": "brd_01m4ttwd3veh9apbewxheq5xh5",
  "createdBy": "usr_01m4ttwd3veh9apbewxheq5xh6",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-20T09:30:00.000Z",
  "expiresAt": null,
  "lastUsedAt": null,
  "revokedAt": "2026-10-20T09:30:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`resource_not_found`	404	No key with this ID is visible in the scope and mode of the request.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`version_conflict`	409	The key changed at the same moment; retry.	Fetch the object again and retry the change.
`permission_denied`	403	You can't manage API keys here.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: validation_failed, api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Revoke a leaked key#

Errors#