API Key Rotation

Rotate keys without downtime. The old key stays valid during an overlap window while your services pick up the new one. When the overlap expires, the old key is deleted automatically.

How it works

Rotate a key. The new key is generated immediately. The old key stays valid for overlapDays (default 7). Your webhook receives a rotationRef — call the reveal endpoint to fetch the raw key. Push it to your secrets store. When overlap ends, the old key is deleted with zero manual intervention.

Rotating a key

cURL

curl -X POST https://api.wardenauthz.com/v1/scope/workspace-eng/api-key/management/key_a1b2c3d4/rotate \
  -H "x-api-key: YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "overlapDays": 7 }'

{
  "keyId": "key_e5f6g7h8",
  "rawKey": "sk_live_eJx1VUd...",
  "oldKeyId": "key_a1b2c3d4",
  "rotationRef": "ref-abc123",
  "overlapExpiresAt": "2026-07-22T14:22:31Z"
}

Auto-rotation

Enable auto-rotation to rotate keys on a schedule without any manual intervention:

cURL

curl -X PATCH https://api.wardenauthz.com/v1/scope/workspace-eng/api-key/management/key_a1b2c3d4/auto-rotation \
  -H "x-api-key: YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "intervalDays": 30, "overlapDays": 7 }'

The system rotates the key every 30 days. Your webhook fires on each rotation.

Prerequisites

• You need a webhook endpoint that WardenAuth can reach.
• Your infrastructure must be able to update secrets at runtime — the webhook delivers a rotationRef, not the raw key. Call the reveal endpoint to get it.
• Services must reload secrets without redeploying. If your secrets are baked into Docker images, auto-rotation won't work.

Edge cases

• The rotationRef is single-use. Once consumed, it's gone.
• Overlap expires with zero latency. The old key stops working at overlapExpiresAt exactly. No partial state.
• If the overlap expires before you deploy the new key, services break. Set overlapDays longer than your maximum deployment time.