Rotate an API key

Creates a replacement key and schedules revocation of the old key. Requires api_keys:manage.

POST/api-keys/{keyId}/rotate

Authorization

AuthorizationBearer <token>

Path parameters

keyIdstringrequired

format: "uuid"

Bodyrequired

application/json

object

labelstring | null

maxLength: 80

scopesarray

minItems: 1
maxItems: 16

Show nested schema

Array items

string

modestring

enum: ["live","test"]

gracePeriodSecondsinteger

minimum: 0
maximum: 604800

Response

application/json

Replacement key with one-time secret

object

idstringrequired

format: "uuid"

objectstringrequired

const: "api_key"

key_prefixstringrequired

keystring

Returned only when a key is created or rotated.

labelstring | null

scopesarrayrequired

Show nested schema

Array items

string

modestringrequired

enum: ["live","test"]

created_atintegerrequired

last_used_atinteger | null

revoked_atinteger | null

updated_atinteger

old_key_revokes_atstring

Returned only when a key is rotated.

format: "date-time"

curl --request POST \
  --url 'https://YOUR_SALAMBO_BASE_URL/api/v1/api-keys/{keyId}/rotate' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '@request.json'

Replace placeholders before running. JSON templates without a sample body read your payload from request.json.

Response

{
  "id": "<string>",
  "object": "api_key",
  "key_prefix": "<string>",
  "key": "<string>",
  "label": "<string | null>",
  "scopes": [
    "<string>"
  ],
  "mode": "live",
  "created_at": 123,
  "last_used_at": 123,
  "revoked_at": 123,
  "updated_at": 123,
  "old_key_revokes_at": "<string>"
}