How to rotate a Cloudflare Workers secret

Updated October 2026

A Cloudflare Workers secret goes live the moment you write it. There's no separate deploy step to remember, and no way to read the old value back to check what you're replacing.

Here's the exact process, from Cloudflare's own docs.

The manual steps

1. Write the new secret: PUT /accounts/{account_id}/workers/scripts/{script_name}/secrets, body {"name": "STRIPE_KEY", "text": "<value>", "type": "secret_text"}. Cloudflare's own docs, checked December 11, 2026, say this "creates a new version of the Worker and deploys it immediately," the same as running wrangler secret put from the CLI.
2. If the Worker uses gradual deployments, use the versioned call instead so a bad secret doesn't go to 100% of traffic at once. Cloudflare's own docs note that wrangler versions secret put "only create[s] a new version," and you deploy it yourself on your own schedule.
3. Confirm the app actually works with the new secret. You can't check the value directly, only the behavior.
4. Delete the old secret once you've confirmed the new one works: DELETE /accounts/{account_id}/workers/scripts/{script_name}/secrets/{secret_name}.

What breaks if you miss a place

Because the write deploys immediately, there's no gap between "saved" and "live" the way there is on Vercel or Render. That's good for speed and bad for safety in the other direction: a typo in the new secret value ships to production the instant you hit save, with no review window built into the API itself.

How to check the old secret is actually gone

Cloudflare's own docs are plain about this: "Secret values are not visible within Wrangler or Cloudflare dashboard after you define them." The GET endpoint's schema lists a text field, but Cloudflare's own example response leaves it out. Verify behavior, not the value: call whatever the Worker protects with the old credential, at the provider it belongs to, and confirm that fails.

Gradual deployments change the picture

If the Worker is mid-rollout between two versions, it's not written down what a plain secret PUT does to the version that's only getting a slice of traffic. Cloudflare's own docs steer you toward the versioned secret call specifically to sidestep that question: write the new version, control the rollout yourself, and the ordinary secret endpoint never gets involved while a gradual split is active.

Treat that as a real gap, not a detail to skip. A secret rotation that lands in the middle of a gradual rollout, using the wrong call, can leave part of your traffic on the old value and part on the new one, with no error telling you that happened. Finish or pause the rollout first, then rotate.

Or let Key Robot do it

Key Robot does this for you today. It writes the new secret, which makes a new Worker version, waits until that version is the one answering, checks your app, and then deletes the old key at the service. Cloudflare never gives a secret back, so the robot keeps its own sealed copy in your robot's GitHub secrets. That copy is what lets it put the old key back if a check fails. The first time, there is no copy yet, so if that first check fails the robot keeps the new key and tells you.

In our live test on October 26, 2026, a change took 12 to 14 seconds. That test also caught a real bug: right after a write, Cloudflare still served the old version for about a second. The robot now waits for the new version before it checks.

See how to rotate a Cloudflare API token for the account-level credential, a different thing from a Workers secret, or the rotate hub for every service.