API Keys

Rotate an API key

Issues a new secret for the same key record (same id, scope and capabilities) and invalidates the previous secret. The new raw key is returned only in this response. Refused for a connected app, like creation: rotation returns a raw secret for a key the caller need never have held, so it reaches the same place by another door.

post/v1/api-keys/{api_key_id}:rotate

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/api-keys/{api_key_id}:rotate
  • Auth: HTTP bearer

Response

Rotated. The new raw key value is only returned here.

idstring required

Public API key ID (key_ prefix).

namestring required
key_prefixstring required

Leading characters of the raw key, for identification.

scope'project' | 'account' required

Whether the key is scoped to one project or the whole account.

project_idstring nullable

The project this key is scoped to; null for account-scoped keys.

capabilitiesstring[] required

Capabilities granted to this key. Empty means it inherits the creator's.

created_atstring date-time required
last_used_atstring date-time nullable

When the key was last presented; null if never used.

keystring required

The raw API key value (only returned once, at creation or rotation). Use as the Bearer token.

Example response

{
  "id": "key_V1StGXR8Z5jdHi6B",
  "name": "CI/CD Pipeline",
  "key_prefix": "nat_sk_a1b2c3",
  "scope": "project",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "capabilities": [
    "agents:read",
    "sessions:write"
  ],
  "created_at": "2026-07-17T00:00:00.000Z",
  "last_used_at": "2026-07-17T09:12:00.000Z",
  "key": "nat_sk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"
}

Changes

No recorded changes to this operation across all 1 revision of this API.