To rotate an AWS IAM access key safely, create the new key before touching the old one, prove the new key works, give every consumer time to switch, and only then remove the old key. Skip any of those steps and rotation becomes an outage.
Most teams know long-lived access keys are risky. Many still have keys that are years old, because the last time someone rotated one, something broke. This guide explains why that happens and a rotation sequence that avoids it.
Why rotation breaks applications
Three things go wrong in the usual "delete the old key, create a new one" routine:
- A gap. Between deleting the old key and the application loading the new one, every call fails.
- Hidden consumers. The key is also in a CI variable, a cron host, or a colleague's laptop. You only learn that when it stops working.
- An unverified new key. The new key is created and stored, but a permissions or policy problem means it does not actually work, and the old key is already gone.
The fix for all three is the same idea: two valid keys for a short overlap.
The constraint you have to design around
An IAM user can have at most two access keys. That is exactly enough for a clean overlap, and exactly why rotation fails when someone has left a second key lying around. If both slots are already used, you cannot create the new key, and the right first step is to find out whether one of them is unused.
AWS can tell you when a key was last used (GetAccessKeyLastUsed). A key that has never been used, or has not been used for months, is the first candidate to remove before you rotate.
A safe rotation sequence
- Preflight. Before changing anything, check that the account doing the rotation can list, create, update and delete the user's keys, that the user exists, and that a slot is free. Fix problems now, while nothing is at stake.
- Create the new key. The old key is untouched and still Active.
- Verify the new key before cutover. Make a real call with it, such as STS
GetCallerIdentity. Do not rely on the key merely having been created. If verification fails, delete the new key and stop; nothing has changed for consumers. - Store the new key where applications read it (a secrets store or vault), and keep the previous value available for the overlap.
- Open a grace window. The old key stays Active for a defined period so any consumer still holding it keeps working while it picks up the new one. Choose the length from how your applications refresh credentials: minutes for apps that re-read on every start, hours for batch jobs, a day for weekly cron.
- Close the window. Delete the old key. Rotation is complete.
- Keep rollback open until then. If something misbehaves during the window, re-activate the old key, restore it in the store, and delete the new key.
A grace window of zero removes the old key immediately. That is sometimes right for an emergency (a suspected leak) and wrong for routine rotation.
Getting applications to switch by themselves
The overlap is only useful if consumers actually move to the new key. Options, in order of preference:
- Fetch at runtime. The application asks a secrets store or an SDK for the key when it needs it, and re-reads on a short interval or on a 401.
- A wrapper that injects it. A small CLI that fetches the key, runs the process with it in the environment, and restarts or refreshes when it changes.
- Hold the previous value too. During the grace window, a consumer that gets a 401 with the current key can retry with the previous one, then re-fetch.
Avoid copying the key into environment files, container images or CI variables. Every copy is a consumer you will forget.
Mistakes to avoid
| Mistake | Why it hurts | Instead |
|---|---|---|
| Rotating on a fixed day with no preflight | Fails halfway when both key slots are used | Run preflight first, report the fix |
| Treating "key created" as "rotation succeeded" | A broken new key is discovered after the old one is deleted | Verify with a live call before cutover |
| Deleting the old key at once | Any consumer that has not refreshed breaks | Keep it Active through a grace window |
| Rotating in the middle of a grace window | Two overlapping rotations leave you with no known-good key | Block a new rotation until the window closes, or close it first |
| Logging the key | The secret ends up in log storage | Log fingerprints (last four characters), never values |
| No schedule | Rotation depends on someone remembering | Schedule it, with a minimum interval longer than the grace window |
How often to rotate
Often enough that a leaked key has a short useful life, and rarely enough that rotation stays boring. For most workloads, 30 to 90 days with a grace window is a sensible starting point, with a shorter interval for keys that can reach production data. The interval must always be longer than the grace window, or a new rotation starts while the previous overlap is still open.
Where the application can use short-lived credentials (an IAM role or temporary credentials) instead of a long-lived key, prefer that and retire the key entirely.
How ZenXPAM supports this
ZenXPAM implements this sequence for AWS IAM keys: preflight checks, creation of the new key, verification before cutover, a grace window during which the old key stays Active, one-click rollback, scheduled rotation, and an audit record of every step that shows key fingerprints but never a key. Its read-only credential inventory finds stale, never-used and ownerless keys first, and the zenx-secret CLI and SDKs deliver the new key to applications. The AWS path has been tested against a live AWS account. See non-human identity governance or book a demo.
FAQ
How many access keys can an IAM user have? Two. That is why a clean rotation needs a free slot, and why an unused second key should be removed first.
How long should the grace window be? Long enough for your slowest consumer to refresh: a few minutes for applications that read the key at start-up, up to a day for scheduled jobs.
What if the new key fails verification? Delete it and stop. The old key was never touched, so consumers are unaffected.
Can I roll back after the old key is deleted? No. That is why rollback is available only during the grace window, and why the window should not be zero for routine rotation.
Should I use keys at all? Where you can, use roles and temporary credentials. Rotation is for the cases where a long-lived key is unavoidable.
