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

Omit to keep the current key's scopes.

minItems: 1
maxItems: 11
uniqueItems: true

Show nested schema

Array items

string

Write and reveal scopes require their read scope (for example run:write requires run:read). Each scope may appear once.

enum: ["models:read","files:read","files:write","agents:read","agents:write","run:read","run:write","env_vars:read","env_vars:write","env_vars:reveal","api_keys:manage"]

modestring

Optional. Rotation always issues a live key.

enum: ["live"]

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

Grants on this key. Active keys hold only canonical scopes; revoked keys keep the scopes they were issued with.

Show nested schema

Array items

string

modestringrequired

Always live for active keys. test appears only on revoked keys issued before test mode was removed.

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>"
}