Rotate the root key
The root key wraps every project key (KEK). Rotating it re-wraps those keys; secret values are
not touched. Every root key has an id, stored with each KEK it wraps: ANCHOR_ROOT_KEY_ID
(default rk1, format ^[a-z0-9-]{1,32}$). While rotating, the old key stays configured as
ANCHOR_ROOT_KEY_PREVIOUS so existing data keeps working.
Each wrangler secret put deploys a new Worker version immediately, and the intermediate states
(a previous key without its id, or a previous id equal to the current id) fail closed: every
secret read and write would return 500 until the last variable is set. So the four variables
change together, in one wrangler secret bulk request.
-
Generate the new key and back it up offline (see step 3 of the deploy guide):
umask 077 && openssl rand -base64 32 > anchor-root-new.key. Restore the current key from its offline backup intoanchor-root.key(sameumask 077shell). -
Write the four variables to a private JSON file, set them in one request, then delete the file.
OLD_IDis the current id (rk1if you never set one);NEW_IDis the new one, for examplerk2:Terminal window umask 077OLD_ID=rk1 NEW_ID=rk2 node -e 'const fs = require("node:fs");const read = (f) => fs.readFileSync(f, "utf8").trim();process.stdout.write(JSON.stringify({ANCHOR_ROOT_KEY_PREVIOUS: read("anchor-root.key"),ANCHOR_ROOT_KEY_PREVIOUS_ID: process.env.OLD_ID,ANCHOR_ROOT_KEY: read("anchor-root-new.key"),ANCHOR_ROOT_KEY_ID: process.env.NEW_ID,}));' > root-rotation.jsonpnpm exec wrangler secret bulk root-rotation.jsonrm root-rotation.json anchor-root.key anchor-root-new.keyBoth keys must already be in your offline backup before the
rm. -
Check the deployment:
GET /api/v1/healthanswers, and a secret read still works. -
As an instance owner, re-wrap every project key:
curl -X POST https://<host>/api/v1/admin/root-key/rewrap -H 'authorization: Bearer <token>' -
Check that
rewrappedequals the number of project key rows, then call it again and expect{ "rewrapped": 0 }. -
Remove the previous key and its id together (a previous key left without its id fails closed):
Terminal window echo '{"ANCHOR_ROOT_KEY_PREVIOUS": null, "ANCHOR_ROOT_KEY_PREVIOUS_ID": null}' > drop.jsonpnpm exec wrangler secret bulk drop.json && rm drop.json -
Confirm the offline backup of the new key, then destroy the old key’s backups only after you no longer need to restore a database backup taken before step 4.
A misconfiguration fails closed with 500 internal. A previous key without its id, or a previous
id equal to the current id, logs config_error. Project keys under a root key id that is not
configured log secret_decrypt_failed (with the projectId and kekVersion) on every read of
that project. A previous key that does not match fails the rewrap with secret_decrypt_failed and
writes nothing.