POST /v1/admin/key/rotate

Self-serve key rotation. Returns the new key exactly once.

What this is

Atomically rotates the authenticated org’s API key. Hashes the new key with the pepper, updates organizations.api_key_hash, prefix, and api_key_rotated_at, increments api_key_version, and returns the new plaintext key in the response body one time only.

When to use

Scheduled rotation (every 90 days), suspected compromise, off-boarding an engineer who had access.

Request

curl -X POST https://api.cohesionauth.com/v1/admin/key/rotate \
  -H "X-API-Key: $OLD_COHESION_API_KEY"

Python

new_key_response = client.admin.rotate_key()
print(new_key_response.new_api_key)   # store immediately

TypeScript

const res = await client.admin.rotateKey();
console.log(res.new_api_key);

Response

{
  "new_api_key": "ck_live_7Z9Q3RXN5VTDWB2MCHKF8YAJ0P",
  "prefix": "ck_live_",
  "rotated_at": "2026-04-22T18:22:10.432Z",
  "warning": "This key is shown only once. Store immediately.",
  "request_id": "req_01H...",
  "timestamp": "2026-04-22T18:22:10.432Z"
}

Errors

Status	Meaning
`401`	Old key invalid or revoked
`429`	Rate limit (admin endpoints share Layer 2)

Next step

See authentication for key-handling best practices.