Rotate a project key
Each project has a key (KEK) that encrypts its secret values. A project admin rotates it with
POST /api/v1/projects/<slug>/keys/rotate (202). That creates a new key version for new writes,
marks the old one retiring, and re-encrypts existing values in the background, 100 versions per
queue message. Every value stays readable throughout. GET /api/v1/projects/<slug>/keys shows the
key versions and the rotation progress (done / total). In the dashboard, the same controls are
on the project’s Encryption page (project admins), which polls while a rotation runs.
- The old key becomes
retiredonly when no stored version uses it any more. - Calling rotate again while a rotation runs resumes it (re-sends its message) instead of starting a second one.
- A batch that keeps throwing (for example a project key that no longer unwraps) is retried with
backoff (30 s, doubling, capped at an hour: about three hours in all); on its 10th attempt the rotation stops with status
failedand errorretries_exhausted, andreencrypt_rotation_failedis logged. Fix the cause, then start a new rotation. The daily Cron Trigger re-sends the message of any rotation stillrunningbut idle for 15 minutes, as does the next rotate call. - A stored value that fails its integrity check stops the rotation with status
failedand errordecrypt_failed, and logssecret_decrypt_failedwith the ids. Treat it as an incident: investigate, then start a new rotation.
Rotating a project key does not touch the root key. To replace the root key, see Rotate the root key.