/v1/workspaces/{workspace_slug}/api-keys/{id}/rotateAuthMint 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*stringSlug 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 · uuidId of the api key.
Request body
grace_hoursnumberHow 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*stringThe full plaintext PAK token. Returned ONCE — store it now; it cannot be retrieved later.
Example: "pcft_live_abc123XYZ..."
record*objectid*string · uuidId of the key.
workspace_id*string · uuidId of the workspace the key belongs to.
created_by*string · uuidAccount id of who minted the key, or `null` when that account is gone.
name*stringName of the key.
description*stringWhat the key is for, when set.
token_prefix*stringThe first ~14 chars of the token (prefix). Plaintext token is never returned after mint.
Example: "pcft_live_abc123"
policies*arrayManaged policies currently bound to this PAK.
last_used_at*string · date-timeWhen the key last authenticated a request, or `null` if never.
revoked_at*string · date-timeWhen the key was revoked, or `null` while it is not.
expires_at*string · date-timeWhen this key stops introspecting. `null` means it never expires.
rotated_from*string · uuidId of the key this one replaced, when it was minted by a rotation.
status*objectLifecycle 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-timeWhen the key was minted.
updated_at*string · date-timeWhen the key was last changed.
rotated_from*string · uuidId of the key this one replaces.
previous_key_expires_at*string · date-timeWhen 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"
}