POST /v1/organizations/:orgId/api-keys/:keyId/rotate

To roll a customer's credential without an outage, rotate the child key. You call this with your parent (org:admin) key. Rotation mints a brand-new key (new id, new secret) carrying the same scopes, env, and tier as the old one - and the old secret keeps working for a 24-hour grace window. That overlap is the point: deploy the new secret across the customer's fleet at your own pace, and the old one stops automatically when the window closes.

This is distinct from rotating your own parent key, which replaces the secret in place and kills the old one instantly. Child rotation is dual-secret by design.

A key can be rotated once. Once you rotate a key it's superseded by its replacement, and rotating that same (superseded) key again returns 409 CONFLICT - rotate the current key instead. The chain rolls forward cleanly: K → K2 → K3, each link rotating the live key, never a retired one.

The new plaintext secret is returned once, in this response. Store it before you do anything else.

Example

NEW_SECRET=$(curl -s -X POST \
  https://api.layers.com/v1/organizations/org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80/api-keys/key_c2037bb9.../rotate \
  -H "Authorization: Bearer $LAYERS_PARENT_KEY" \
  -H "Idempotency-Key: $(uuidgen)" | jq -r .secret)

# Deploy NEW_SECRET to the customer's services within 24h.
# The old secret keeps working until then, so there's no flap.

{
  "apiKey": {
    "id": "key_9a44e1f0-...",
    "organizationId": "org_d4e5f6a7-8b9c-4d0e-9f2a-3b4c5d6e7f80",
    "name": "acme-content-sync",
    "prefix": "lp_live_TUVWXYZ23456789",
    "env": "live",
    "scopes": ["content:read", "content:write"],
    "rateLimitTier": "standard",
    "status": "active",
    "createdAt": "2026-06-03T20:31:10.552Z",
    "lastUsedAt": null,
    "rotatedAt": null,
    "revokedAt": null,
    "graceUntil": null,
    "supersededBy": null
  },
  "secret": "lp_live_...",
  "warning": "Store this secret now. It cannot be retrieved again. Rotate the key if it's lost."
}

The response is the new key - the customer's go-forward credential. To observe the old key's grace window, list the child's keys: the old row now carries graceUntil (when its secret stops) and supersededBy (the new key's id).

Rotation runbook

Errors

See also

• Mint a child key - create the original key.
• List - read graceUntil / supersededBy on the old key.
• Delete - kill the old secret immediately instead of waiting out the grace.
• API keys → rotation grace window - the concept and playbook.