Rotate JWT Secrets Without Downtime

Rotate production JWT secrets without forcing a global logout. Generate a new secret in the browser, publish it under a new kid, verify both old and new keys during an overlap window, then retire the old secret after in-flight tokens expire.

Last updated August 26, 2026

Steps

  1. 1

    Generate a new 256-bit secret with the JWT Secret Generator and store it as JWT_SECRET_NEXT (never commit it).

  2. 2

    Assign a unique kid to the new key (for example kid=v2) and keep the previous key available as JWT_SECRET with kid=v1.

  3. 3

    Update your signer to issue new tokens with the new secret and kid header.

  4. 4

    Update verifiers to accept both kids during an overlap window at least as long as your max access-token lifetime.

  5. 5

    After the overlap, remove the old secret from verifiers and secrets storage, then audit that no services still sign with v1.

  6. 6

    Document the rotation in your runbook and rehearse it in staging before production.

Generate Replacement Secret

Related Articles

How To Rotate Jwt SecretsHow To Store Jwt Secrets SecurelyJwt Best Practices ChecklistJwks In Production

Frequently Asked Questions

Do I need the kid header to rotate secrets?

kid is the cleanest approach for dual-key verification. Without it you can still try multiple secrets, but kid makes selection explicit and safer at scale.

How long should the overlap window last?

At least as long as your longest-lived access token. If you issue 1-hour tokens, keep both keys for a bit more than one hour after cutover.

Should I rotate refresh-token secrets too?

Yes, but plan separately — refresh tokens often live days or weeks, so the overlap window is longer and may require re-login for some users.

What if a secret was leaked?

Treat it as emergency rotation: publish a new key immediately, revoke or shorten sessions where possible, and retire the leaked secret as soon as you can tolerate invalidating old tokens.