Rotate an API key

POST /v1/api-keys/{key_id}:rotate · permission api-keys:write · optional Idempotency-Key

Rotates a key: creates a NEW key with the same name, type, permissions and allowed_cidrs, and returns it. The old key stays valid for overlap_hours, then stops working.

New key. The response describes the new key; rotated_from is the old key's id and key carries the raw key once (Cache-Control: no-store). Deploy it, then let the old key lapse.
Overlap. The old key gets revoked_at in the future and revoke_reason: rotated; with overlap_hours: 0 it is revoked immediately.
No escalation. A key cannot rotate a key whose permissions exceed its own, and a restricted key cannot rotate a secret key. The new key cannot expire after the calling key, even when a key rotates itself (extend a lifetime in the dashboard), and a calling key with allowed_cidrs can only rotate keys limited to networks inside its own. A key created in the dashboard, and every key rotated from it, can be rotated only by itself or in the dashboard (permission_escalation). The new key keeps the old key's created_by; the rotating key is recorded in the audit log.
Idempotent replay. A replay with the same Idempotency-Key omits key and returns secret_redacted: true.

Request

Parameter	In	Description
`key_id`	path	API key id (`key_…`).

Body:

The body is optional; without it all defaults apply.

Field	Type	Description
`overlap_hours`	integer	Optional, 0–168, default 24. How many hours the old key stays valid.
`expires_at`	string (date-time)	Optional. Expiry of the NEW key; default now + 365 days, at most the calling key's expiry and at most 730 days.

Response

200 OK with Cache-Control: no-store. The NEW key object plus key.

{
  "id": "key_0000000000000000000000001z",
  "name": "ci",
  "type": "restricted",
  "permissions": ["users:read"],
  "allowed_cidrs": [],
  "last4": "xxxx",
  "created_by": "key_…",
  "created_at": "2026-10-01T10:00:00Z",
  "expires_at": "2027-10-01T10:00:00Z",
  "last_used_at": null,
  "last_used_ip": null,
  "rotated_from": "key_…",
  "revoked_at": null,
  "revoke_reason": null,
  "key": "<shown once>"
}

Errors

HTTP	`code`	When
401	`unauthenticated`	The key is missing, invalid or revoked.
403	`insufficient_permissions`	The key lacks the required permission.
403	`permission_escalation`	The request would give a key more permissions, a wider network range or a later expiry than the calling key has, a `restricted` key tries to create, rotate or revoke beyond its own permissions, or another key tries to rotate or revoke a key created in the dashboard.
404	`not_found`	The key does not exist in this environment.
409	`conflict`	The key is already revoked, expired or already rotated (not active).
409	`api_key_limit_reached`	The environment already has the maximum of 50 active keys.
422	`validation_failed`	The body is invalid: `overlap_hours` outside 0–168 or `expires_at` in the past or more than 730 days ahead.

Example

curl -X POST "https://api.eu.keenauth.com/v1/api-keys/key_0000000000000000000000001z:rotate" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"overlap_hours":24}'