Rotate an API key's secret

POST

/api-key-rotations

Generates a new key pair for an existing API key, immediately invalidating the previous secret. The public key is updated in place and the new secret key is returned in plaintext exactly once — save it immediately, as it cannot be retrieved again. The key's id, name, environment, and other metadata remain unchanged. The key must belong to the authenticated identity or its entity, must currently be active, and must not be the sandbox master key. Optionally set overlap_seconds to keep the previous secret valid for a grace period after rotation, useful for zero-downtime credential swaps.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Key rotated successfully. The new public_key and secret_key are returned. Unless overlap_seconds was supplied, the old secret is now invalid. Store the secret_key immediately — it will not be returned again.

Bodyapplication/json

🟠400

🟠401

🟠403

🟠404

Request Example

Shell

JavaScript

Java

Swift

cURL

Rotate immediately, no grace periodRotate with a 1-hour overlap window

curl --location '/api-key-rotations' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "id": "01J5X8PMKW3RNVBQE2D7F9GHAT"
}'

Response Example

200 - Rotation without an overlap window

{
    "message": "API key rotated successfully",
    "status": "success",
    "data": {
        "id": "01J5X8PMKW3RNVBQE2D7F9GHAT",
        "name": "Production Server Key",
        "environment": "live",
        "identity_id": "01J5X8PMKW3RNVBQE2D7F9GHBT",
        "public_key": "pk_live_9c3b2d8e4f1a5b6c",
        "secret_key": "sk_live_4f1a5b6c9c3b2d8e",
        "last_reset": 1754651520000,
        "expires_at": null,
        "status": "active",
        "overlap_expires_at": null
    }
}

Modified at 2026-09-30 00:29:30

Revoke an API key

Delete an app setting value