Secret Rotation
Secret rotation replaces credentials on a schedule or after compromise, using overlapping validity windows so consumers switch without downtime.
Definition
Secret rotation is the operational practice of periodically issuing new credentials, distributing them to consumers, verifying they work, and retiring the old ones, with a defined overlap window that avoids outages.
Context and scope
Use it for database passwords, API keys, signing secrets, and webhook keys, and always after a suspected leak or personnel change.
Common misconceptions
- Rotation is just generating a new value; every consumer must reload it and the old value must be retired
- Rotation prevents leaks; it only limits how long a leaked credential stays useful
- Rotating every secret at once is efficient; it creates a single large outage risk
Anti-patterns
- Storing the new secret but never restarting or reloading the consumer
- Disabling the old credential before traffic has drained
- Keeping a hardcoded fallback secret that never rotates
Related concepts
Related examples
Authoritative source
https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html
Rotation is a workflow
Generating a new password is the easy part. Rotation is the full loop: create a new version, distribute it, make consumers use it, confirm healthy traffic, and only then revoke the old version. Skipping the middle steps produces either an outage or a credential that never actually changes.
How it works
A rotation job asks the secret store for a new version, updates the target system, and writes the new value with a version label such as AWSCURRENT. The previous value moves to AWSPREVIOUS and stays valid during the overlap window. Consumers read the current version at startup and on a refresh signal, then reconnect.
For databases, the safest pattern creates a second credential for the same role, deploys it, waits for connection churn, and then deletes the first. For API keys, accept two keys concurrently and publish which one is primary. For signing secrets, verify with both keys while new tokens are signed with the new one.
When to use it
Rotate on a fixed schedule for long-lived credentials, immediately after any suspected exposure, and when someone with access leaves. High-value secrets may rotate every few hours; low-risk internal keys may rotate quarterly. Rotation is not a substitute for short-lived credentials, which remove the problem entirely.
Trade-offs
Frequent rotation increases the chance of a failed reload, especially with cached clients and long-lived connections. Overlap windows widen the period when two secrets are valid, which slightly increases exposure. Automated rotation adds infrastructure and requires the application to cooperate; without a reload path, automation only creates drift.
Example and misconceptions
A service caches its database password at boot and never refreshes. Automation rotates the password, and the next connection attempt fails. Adding a reload hook and a dual-credential window turns the same rotation into a no-op for users.
The common misconception is that the secret manager rotates the application. It rotates the value; the application must adopt it.
Related concepts: Secret Management, Key Rotation, and Least Privilege.