Secret Rotation: When and How to Rotate Keys

Even the strongest secret shouldn't live forever. Rotation — replacing a secret with a fresh one on a schedule or in response to an event — limits the damage if a key is ever exposed and is increasingly required by security and compliance standards. The trick is doing it without breaking your application.

Why rotate at all?

• Limit exposure. A secret leaked today is useless tomorrow if it's already been rotated out.
• Reduce blast radius. Shorter lifetimes mean a compromised key unlocks less, for less time.
• Personnel changes. Rotate when someone with access leaves.
• Compliance. Many frameworks mandate periodic rotation.

What should trigger a rotation

• Time-based: on a fixed schedule (e.g. every 90 days for long-lived keys).
• Event-based: immediately after a suspected leak, a committed .env, or an offboarding.
• Usage-based: some systems rotate after a certain number of uses or issued tokens.

The zero-downtime pattern: overlap

The reason naive rotation causes outages is that the moment you swap a secret, anything still relying on the old one breaks. The fix is to support two valid secrets at once during a transition window:

1. Introduce the new secret alongside the old; configure systems to accept both but issue/sign with the new one.
2. Drain — wait for everything signed with the old secret to expire or be reissued.
3. Retire the old secret once it's no longer in use.

This overlap is why key versioning matters: tag each key with an identifier (a JWT kid header, a key version column) so verifiers know which key produced a given value.

Rotating different secret types

• JWT signing secrets: publish multiple valid keys and select by kid; keep lifetimes short so old tokens drain quickly. See JWT signing.
• API keys: let users create a new key, run both in parallel, then revoke the old — exactly the flow in API key best practices.
• Encryption keys: version your keys; encrypt new data with the new key while keeping old keys available to decrypt existing data ("envelope encryption" makes this clean).

Make rotation routine

Rotation should be boring. Automate it where possible, store secrets in a manager that supports versioning, document the runbook, and rehearse it — so that when you must rotate in a hurry after an incident, it's a practiced motion rather than a panic.

Generate the replacement

When it's time to roll a key, generate the new one here — JWT secrets, encryption keys, API tokens, and full .env bundles — all created locally in your browser so the new secret never touches a server.