Password Rotation: Good or Bad? settles the question of whether a credential should rotate on a schedule: not for a password a human has to remember, but yes for one a machine generates — API keys, database service-account passwords, cloud IAM access keys, certificates. That post stops at should. This one covers how — because rotating a machine credential safely is a specific, multi-step operation, and skipping steps is exactly what turns a routine rotation into an outage.
What actually needs rotating
Anything a service presents to authenticate itself, rather than a human typing a password, falls into this category: API keys, database and service-account passwords, cloud IAM access keys, TLS/mTLS certificates, SSH keys, webhook signing secrets, OAuth client secrets, and JWT signing keys. All of these share the property that makes scheduled rotation safe in the first place — a fresh value is generated by a CSPRNG or key pair, not thought up by a person, so there's no predictable-successor pattern for an attacker to exploit between one value and the next.
The problem scheduled rotation actually has to solve
Rotating a credential isn't swapping one string for another in one place. A given secret is usually live in more locations than anyone has a complete list of: the service that issued it, every application config or secrets-manager entry that holds a copy, every CI job that injects it, and sometimes a third-party integration that was configured with it once and never touched again. Revoke the old value the instant the new one exists, and every copy you missed fails at once — that's the outage. The entire discipline of safe rotation is built around avoiding exactly that.
The overlap window: the pattern that makes it safe
Every reliable rotation procedure is a variation on the same four steps, and the order matters more than any individual step:
- 1. Provision the new credential without touching the old one. Generate the replacement value and register it wherever the issuer requires — a new IAM access key, a new database user or password, a new API key — while the existing credential stays fully valid. At this point, nothing that depends on the old value has changed yet.
- 2. Deploy the new value everywhere the old one is used, in parallel. Update every config, secrets-manager entry, and CI variable to the new value while the old one is still live. Both credentials work during this window, which is what makes it safe to roll out gradually instead of everywhere at once.
- 3. Verify the new value is actually the one in use. Check access logs, authentication metrics, or the issuer's own last-used timestamp for the old credential. A service or job still authenticating with the old value at this point is a copy you haven't found yet — the whole reason this step exists is to catch it before the next one makes it fail.
- 4. Revoke the old credential. Only once nothing is observed using it. This is the step that actually completes the rotation — and the one most commonly skipped, which leaves a supposedly-rotated credential still valid indefinitely.
JWT Security Best Practices walks through this exact pattern for a signing key specifically — a verifier that accepts multiple valid keys at once during the overlap window, so rotating the key doesn't invalidate every outstanding token the moment the new key goes live.
Scheduled rotation vs. event-driven rotation
Both matter, for different reasons. Scheduled rotation on a fixed interval bounds the exposure window of a compromise nobody has detected yet — the same hedge Password Rotation: Good or Bad? describes, just applied to a credential where regenerating on schedule carries no downside. Event-driven rotation is the response to a specific trigger: a credential appears in a log or a public repository, a vendor discloses a breach, an employee or contractor with access leaves, or monitoring flags anomalous use. Event-driven rotation should happen immediately, not on the next scheduled cycle — the four-step sequence above still applies, just compressed and run as an incident rather than routine maintenance.
Where automation actually does this for you
The overlap-window discipline above is exactly what a dedicated secrets manager automates, which is a large part of the case .env vs Secrets Managers makes for adopting one: AWS Secrets Manager's rotation Lambdas and IAM's access-key rotation both implement create-new / deploy-alongside-old / verify / revoke-old as a managed workflow rather than a manual runbook. Vault's dynamic secrets go further — credentials are issued with a lease and expire automatically, which turns rotation from something you have to remember into something that just happens. Certificates have their own version of this: ACME-based automatic renewal (Let's Encrypt and similar) reissues and swaps a certificate before it expires, on the same overlap principle, without a person running the sequence by hand.
Common mistakes
- Skipping the overlap window. Generating a new credential and revoking the old one in the same step, with no verification in between — this is what turns routine rotation into an outage, and it's the single most avoidable failure mode here.
- Never actually completing step four. The new credential goes live, the old one keeps working, and nobody circles back to revoke it. Months later there are two valid credentials where there should be one, and the old one is exactly the kind of forgotten-but-live secret an audit or an incident response has to account for.
- Missing a copy. A hardcoded value in a script, a cached container image, a third-party integration configured once and never revisited — none of these pick up the new value automatically, and they fail silently until the old credential is revoked, which is precisely why the verification step exists rather than trusting a mental list of everywhere a secret lives.
- Rotating everything simultaneously with no rollback path. If a new credential turns out to be misconfigured, having the old one already revoked means there's no fast way back. Keeping the old credential valid until verification passes is also what makes rotation reversible.
- Treating rotation as compromise response only. Waiting for a known leak before ever rotating a machine credential gives up the exposure-window hedge that scheduled rotation provides for free, precisely because none of the human-memorized-secret downside applies here.
If a credential has actually leaked
Event-driven rotation changes the ordering: revoke first, even before the replacement is fully rolled out, because the risk of a brief outage is smaller than the risk of a known credential staying valid a moment longer than necessary. From there, audit what the leaked credential had access to — its IAM policy or equivalent scope defines the actual blast radius — and check whether anything it could reach shows unexpected access in that same window. Rotate anything downstream that the compromised credential could have read or modified, not just the credential itself.
FAQ
How often should API keys rotate on a schedule?
There's no universal number — it depends on how automated the rotation is and what the credential can access. A fully automated rotation (a secrets manager or dynamic-secret system handling all four steps) can run on a short interval, days or weeks, with no operational cost. A manual process is realistically rotated far less often, which is itself a reason to automate it rather than to pick a longer interval and call it sufficient.
Do certificates need the same overlap-window pattern?
Yes, and ACME auto-renewal is built around it — a new certificate is issued and installed before the old one expires, so there's a window where either would validate, rather than a hard cutover at the expiry instant.
What's the difference between rotation and revocation?
Rotation is the full replace-and-retire sequence above; revocation is just the last step — making a specific credential permanently invalid. Revocation alone, without a new credential already deployed, is what you do in response to a leak when continuity matters less than shutting off access immediately.
Does this apply to encryption keys, not just authentication credentials?
The same overlap discipline applies, with one addition: data already encrypted under the old key doesn't automatically become readable under the new one, so key rotation for encryption (as opposed to authentication) usually needs a re-encryption step or a key version stored alongside the data, not just a swap at the point where new data gets written.
Try it yourself
Environment Variable Diff catches a config that still has the old value in one place and the new one in another mid-rotation, and .env Validator catches the parsing gotchas that hide a stray leftover value. GitHub Actions Secrets Checker traces where a workflow's secrets flow, which is exactly the kind of hidden copy step three above is meant to catch. All three run entirely in your browser.