Rotate an API key
Create a new key with the same scopes and label as the named key, and
revoke the old key in the same step. The new secret is returned only
once in the plaintext field, just like key creation, so store it
before the response is discarded. The old secret stops authenticating
immediately.
Unknown or cross-organization ids return 404 NOT_FOUND. Requires the
apikeys:write scope. Rotation is rate limited to 10 per minute (shared
with key creation); bursts return 429 RATE_LIMITED with a Retry-After
header.
Authenticate by sending your API key as a bearer token:
Authorization: Bearer am_live_.... Every request is automatically
scoped to the organization that owns the key and to the scopes granted
to that key.
In: header
Path Parameters
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/api-keys/497f6eca-6276-4993-bfeb-53cbbbba6f08/rotate"{
"id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3c0",
"org_id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b5",
"label": "order-confirmations bot",
"prefix": "am_live_oc02",
"scopes": [
"messages:send"
],
"created_at": "2026-04-26T14:00:00Z",
"last_used_at": null,
"revoked_at": null,
"plaintext": "am_live_oc02zyxwvutsrqponmlkjihgfedcba9876"
}{
"success": false,
"error": {
"code": "VALIDATION_FAILED",
"message": "validation failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM",
"details": {
"to": "must be E.164",
"body": "must be 1..1600 chars"
}
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "authentication failed",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "missing required scope",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "NOT_FOUND",
"message": "not found",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "rate limited",
"request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
}
}