Skip to main content
POST
/
v1
/
api-keys
/
{id}
/
rotate
Rotate API Key
curl --request POST \
  --url https://api.example.com/v1/api-keys/{id}/rotate
{
  "id": "key_Mc2eF6gH",
  "object": "api_key",
  "name": "Production Backend",
  "key": "sig_live_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0",
  "prefix": "sig_live_z9y8",
  "scopes": ["trademarks:read", "search:read", "portfolios:manage", "events:read"],
  "created_at": "2025-09-10T08:00:00Z",
  "livemode": true,
  "request_id": "req_xQ3hI9jK"
}

​
Overview

Rotates an existing API key by generating a new secret while preserving the key’s name, scopes, and configuration. The old key remains valid for a fixed 24-hour grace period to allow for zero-downtime credential rotation in distributed systems. The new key secret is returned only once in the response. Store it securely immediately.
The grace period is fixed at 24 hours and is not configurable. The old key will automatically stop working 24 hours after rotation.

​
Path Parameters

​
id
string
required
API key ID to rotate (e.g., key_Mc2eF6gH)

​
Response

​
response
object
{
  "id": "key_Mc2eF6gH",
  "object": "api_key",
  "name": "Production Backend",
  "key": "sig_live_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0",
  "prefix": "sig_live_z9y8",
  "scopes": ["trademarks:read", "search:read", "portfolios:manage", "events:read"],
  "created_at": "2025-09-10T08:00:00Z",
  "livemode": true,
  "request_id": "req_xQ3hI9jK"
}

​
Code Examples

curl -X POST https://api.signa.so/v1/api-keys/key_Mc2eF6gH/rotate \
  -H "Authorization: Bearer sig_live_xxxxxxxxxxxx"

​
Errors

StatusTypeDescription
401unauthorizedMissing or invalid API key
403forbiddenInsufficient permissions to rotate keys
404not_foundKey ID does not exist
429rate_limitedToo many requests