Platform API reference

Platform API · Platform-Api-Keys

post/v1/workspaces/{workspace_slug}/api-keys/{id}/rotateAuth

Mint a replacement for an existing PAK, carrying its name, description and policy bindings over. The outgoing key keeps working for `grace_hours` (24 by default) so a fleet can roll over without downtime. The plaintext `token` is returned ONCE. Cookie/JWT only — a PAK cannot rotate a PAK, for the same reason it cannot mint one.

Path parameters

workspace_slug*string

Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve("acme")`); the product APIs bind `workspace_id` instead.

id*string · uuid

Id of the api key.

Request body

grace_hoursnumber

How long the OUTGOING key keeps working, in hours. `0` kills it immediately. Capped at 168 (7 days) — rotation answers "this key may be compromised", so an unbounded overlap would defeat the point. Rotation can only ever shorten a key: if the old one was already due to expire sooner, that earlier instant stands.

Example: 24

Response · 201

token*string

The full plaintext PAK token. Returned ONCE — store it now; it cannot be retrieved later.

Example: "pcft_live_abc123XYZ..."

record*object
id*string · uuid

Id of the key.

workspace_id*string · uuid

Id of the workspace the key belongs to.

created_by*string · uuid

Account id of who minted the key, or `null` when that account is gone.

name*string

Name of the key.

description*string

What the key is for, when set.

token_prefix*string

The first ~14 chars of the token (prefix). Plaintext token is never returned after mint.

Example: "pcft_live_abc123"

policies*array

Managed policies currently bound to this PAK.

last_used_at*string · date-time

When the key last authenticated a request, or `null` if never.

revoked_at*string · date-time

When the key was revoked, or `null` while it is not.

expires_at*string · date-time

When this key stops introspecting. `null` means it never expires.

rotated_from*string · uuid

Id of the key this one replaced, when it was minted by a rotation.

status*object

Lifecycle state at the time of the request. Only `active` keys introspect. `revoked` beats `expired` — revocation is a deliberate act by a named actor and the row keeps saying so.

created_at*string · date-time

When the key was minted.

updated_at*string · date-time

When the key was last changed.

rotated_from*string · uuid

Id of the key this one replaces.

previous_key_expires_at*string · date-time

When the replaced key stops introspecting. Until then BOTH keys work, so a fleet can roll over without downtime. Downstream services cache introspection for 60s, so treat this instant as "+ up to a minute" when planning a cutover.

Example

Request

POST https://api.platform-auth.productcraft.co/v1/workspaces/{workspace_slug}/api-keys/{id}/rotate
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "grace_hours": 24
}

Response

{
  "token": "pcft_live_abc123XYZ...",
  "record": {
    "id": "00000000-0000-0000-0000-000000000000",
    "workspace_id": "00000000-0000-0000-0000-000000000000",
    "created_by": "00000000-0000-0000-0000-000000000000",
    "name": "string",
    "description": "string",
    "token_prefix": "pcft_live_abc123",
    "policies": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "mail-readonly",
        "description": "string"
      }
    ],
    "last_used_at": "2026-01-01T00:00:00.000Z",
    "revoked_at": "2026-01-01T00:00:00.000Z",
    "expires_at": "2026-01-01T00:00:00.000Z",
    "rotated_from": "00000000-0000-0000-0000-000000000000",
    "status": {},
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  },
  "rotated_from": "00000000-0000-0000-0000-000000000000",
  "previous_key_expires_at": "2026-01-01T00:00:00.000Z"
}