What Is Secret Rotation?
Secret rotation is replacing a credential with a new one on a schedule and retiring the old value, limiting how long any leaked secret stays useful.
Definition
Secret rotation is the practice of replacing a credential with a new one on a regular schedule and retiring the old value. The point is to limit the useful lifetime of any single secret: even if a key leaks without anyone noticing, rotation guarantees it stops working after a bounded window. A rotated secret that an attacker captured last month is dead weight by the time they try to use it.
A full rotation is more than generating a new value. It means issuing the replacement, distributing it to every system that needs it, cutting traffic over to the new credential without downtime, and then revoking the old one so it can no longer authenticate. Done well, the overlap window is short and the change is invisible to users. Done badly — a new key deployed to half the fleet while the old one is revoked — it is an outage. The difficulty of that cutover is the real reason teams skip rotation, not the generating of new values.
Why it matters
Every long-lived secret is a standing risk that grows with age. The longer a credential exists, the more copies accumulate — in backups, in old CI configs, in a former employee's shell history — and the more chances it has had to leak undetected. Rotation caps that exposure. It turns “this key has been valid for three years and we have no idea who has seen it” into “this key is at most 30 days old.”
Rotation is also a baseline expectation in most compliance frameworks. SOC 2, PCI-DSS, and similar regimes call for credentials to be changed periodically and immediately after a suspected compromise or a personnel change. Beyond the checkbox, rotation is the mechanism that makes revocation real: when someone leaves the team, rotating the secrets they could read is what actually closes their access, since a permission change alone does nothing about a value they already copied.
Examples
Rotation shows up in a few recurring patterns:
- Scheduled rotation — a database password or API key replaced every 30, 60, or 90 days as a matter of routine, often automated so no human has to remember.
- Event-driven rotation — rotating immediately when an engineer with access leaves, when a laptop is lost, or when a scanner flags a key in a public repo.
- Overlapping (zero-downtime) rotation — issuing the new credential and accepting both old and new for a grace period, deploying the new one everywhere, then revoking the old. This is how you rotate without an outage.
- Dynamic, short-lived credentials — the extreme version, where secrets are minted on demand with a lifetime of minutes, so rotation is continuous and there is no long-lived value to leak.
The anti-pattern to avoid: rotating a value in one place and forgetting the three other systems that still use the old one. Rotation is only as good as your inventory of where each secret lives, which is why teams that track secrets centrally rotate far more often than teams that hunt them down by hand.
Related terms
- Secrets in DevOpsCredentials like API keys, passwords, and tokens that grant access and must stay confidential — and how they differ from config.
- Environment Variables vs SecretsWhy a delivery mechanism and a sensitive credential are not the same thing — and how to store each one safely.
- SAML for Secrets ManagementHow single sign-on governs who can reach your secrets — and why identity is a separate guarantee from encryption.
How Capy helps
Two things make rotation cheap with Capy. First, secrets are tracked centrally as versioned values rather than scattered across .envfiles, so when you rotate you can see every place a value is referenced instead of guessing. Updating a secret pushes the new ciphertext to every teammate's machine, so the cutover does not depend on chasing people in chat.
Second, Capy makes the most common rotation trigger — someone leaving — almost free. capy kick destroys the service-side wrap on that person's key, making their local copies cryptographically inert without forcing the rest of the team to rotate everything. You still rotate any value that was genuinely exposed, but the “rotate-because-someone-might-have-read-it” ritual shrinks dramatically. For why this matters, see what are secrets in DevOps.
Frequently asked questions
How often should secrets be rotated?+
A common baseline is every 30 to 90 days for standing credentials, with immediate rotation after any suspected exposure or personnel change. High-value or high-blast-radius secrets warrant shorter windows; the most security-conscious teams move to short-lived, dynamically issued credentials so rotation is effectively continuous.
What is zero-downtime secret rotation?+
It is rotating a credential without an outage by overlapping the old and new values. You issue the new secret, configure systems to accept both for a grace period, deploy the new one everywhere, then revoke the old one. The overlap window is what prevents a gap where neither credential works.
Why is rotating secrets so hard in practice?+
The hard part is not generating a new value — it is the cutover. You have to find every system using the old secret, distribute the new one to all of them, switch over without downtime, and then revoke the old value. Teams skip rotation because they lack a reliable inventory of where each secret lives.
Do I still need rotation if I revoke access when someone leaves?+
Usually yes. A permission change stops future access through the system, but it does nothing about a value the person already copied to their laptop. Rotating the secrets they could read is what actually invalidates those copies. Cryptographic revocation, like Capy's capy kick, narrows but does not entirely remove the need to rotate genuinely exposed values.
Install Capy in 30 seconds
brew install capysc/tap/capynpm i -g @capy/cli