Rotating an AWS IAM access key breaks production when the old key is deleted before every consumer has moved to the new one. IAM gives each user two key slots precisely so that you can overlap the old and new key, watch the old one go quiet, deactivate it, and only then delete it. This guide walks through that overlap method with the AWS CLI commands from the IAM documentation, how to prove that nothing still uses the old key with last-used data and CloudTrail, and how to roll back in seconds. It is for cloud and platform engineers who own IAM users that still need long-term keys. For the wider context on when access keys are acceptable at all, see the AWS Access Keys Security Guide.
This is an independent guide from NHI Mgmt Group, based on AWS's public documentation as of November 2026. It is not sponsored or reviewed by AWS. Product features change, so confirm settings against AWS's current documentation.
Key takeaways
- Use both key slots. Each IAM user can have at most two access keys, so you create the new key while the old one stays active.
- Deactivate, never delete first.
update-access-key --status Inactiveis reversible;delete-access-keyis not, and IAM requires a key to be deactivated before deletion in the console. - Prove the old key is quiet. Check
get-access-key-last-usedafter several days and search CloudTrail byAccessKeyIdbefore you deactivate. - The secret is shown once. Write the new secret straight into the secret store your consumers read from, never into a ticket or chat.
- Rotation is a stopgap. AWS recommends temporary credentials through roles; every rotation is a chance to remove the key entirely.
When you need this
- Scheduled rotation: the AWS Config managed rule
access-keys-rotated(identifierACCESS_KEYS_ROTATED) marks an IAM user NON_COMPLIANT when an active key is older thanmaxAccessKeyAge, which defaults to 90 days. - Staff or supplier change: AWS's own guidance names an employee leaving as a reason to update keys. The same applies when a contractor or vendor that held the key ends the relationship.
- Precautionary rotation after a provider incident: when a provider you gave credentials to reports an incident, rotate the credentials you supplied, API access keys first. A no-downtime method matters most when you have to rotate dozens of keys on the same day.
- Not for a confirmed leak: if the key is known to be exposed, speed beats overlap. Deactivate immediately and follow the Cloud Access Key Leak Playbook. Leaked keys are often tested within minutes.
Before you start
| Check | Why it matters | How |
|---|---|---|
| The user has only one key | With two keys already present, you cannot create a third | aws iam list-access-keys --user-name <user-name> |
| You know every consumer | Missed consumers are the cause of rotation outages | Last-used service and Region, CloudTrail by key ID, the credential report, owner interview |
| Consumers read from a secret store | Updating one store entry is faster and safer than editing many hosts | AWS Secrets Manager, Parameter Store, Vault or CI secret variables |
| You have IAM permissions | Rotation needs create, update, delete and last-used actions on the user | iam:CreateAccessKey, iam:UpdateAccessKey, iam:DeleteAccessKey, iam:GetAccessKeyLastUsed, iam:ListAccessKeys |
| Not the root user | AWS says not to use root credentials to create access keys; root keys should not exist | Credential report root row |
Generate a baseline credential report first. It shows, for each user, access_key_1_active, access_key_1_last_rotated, access_key_1_last_used_date, access_key_1_last_used_service and the same for key 2. IAM produces a new report at most once every four hours.
aws iam generate-credential-report
aws iam get-credential-report --query Content --output text | base64 --decode > credential-report.csv
Step-by-step
Steps 1 and 2 are read-only. Steps 3 to 6 change the user's credentials; step 7 is destructive.
- Record the current state. List the keys and note the old key ID, its creation date and status.
aws iam list-access-keys --user-name <user-name> - Find every consumer of the old key. Last-used shows only the most recent service and Region, so pair it with CloudTrail event history, which can look up management events from the last 90 days by
AccessKeyId.
Event history is per Region, so repeat across the Regions the key is used in. Group results by source IP address and user agent to list distinct consumers. CloudTrail notes thataws iam get-access-key-last-used --access-key-id <OLD_ACCESS_KEY_ID> aws cloudtrail lookup-events --lookup-attributes AttributeKey=AccessKeyId,AttributeValue=<OLD_ACCESS_KEY_ID>accessKeyIdcan be absent or empty in some events, so treat this as strong evidence, not a complete list. - Create the new key. The new key is active immediately, so the user now has two active keys.
The response contains the secret access key, which cannot be retrieved again. Pipe it into your secret store rather than the terminal history where possible. In the console, the equivalent is IAM > Users > user > Security credentials > Access keys > Create access key, with a description tag that names the consumer and the rotation date.aws iam create-access-key --user-name <user-name> - Update every consumer. Write the new key to the secret store, then restart or reload each consumer so it picks up the change. Applications that cache credentials at start-up keep using the old key until restarted. Update CI variables, scheduled jobs, on-premises hosts with
~/.aws/credentialsfiles (stored in plaintext, which AWS warns about) and any third-party SaaS that was given the key. - Watch the old key go quiet. Wait several days, as AWS advises, and long enough to cover weekly and month-end jobs. Re-run
get-access-key-last-usedon the old key; theLastUsedDateshould stop moving, and the new key should show activity from the expected services. A fresh credential report gives the same picture for both slots in one row, which is useful when you are rotating many users in parallel. If the old key's last-used service or Region changes during the wait, a consumer you did not know about has just run: find it before going further. - Deactivate the old key (reversible).
AWS recommends deactivating even when last-used shows no recent use. Leave it inactive for a further agreed period, for example two weeks, while you watch for errors.aws iam update-access-key --user-name <user-name> --access-key-id <OLD_ACCESS_KEY_ID> --status Inactive - Delete the old key (destructive).
Deletion frees the slot for the next rotation and ends the old key for good.aws iam delete-access-key --user-name <user-name> --access-key-id <OLD_ACCESS_KEY_ID>
Verify it worked
- Key state:
list-access-keysshows one active key with a recent creation date. - New key in use:
get-access-key-last-usedon the new key returns a currentLastUsedDateand the services you expect. - No denied calls: CloudTrail shows no
InvalidClientTokenIdor access denied errors from the consumers during the inactive period. AWS recommends CloudWatch alarms on denied access attempts, which catch a forgotten consumer quickly. - Compliance: the
access-keys-rotatedConfig rule returns COMPLIANT for the user on its next periodic evaluation, andaccess_key_1_last_rotatedin a fresh credential report shows the new date.
Rollback and common errors
| Symptom | Likely cause | Fix |
|---|---|---|
| A consumer fails after deactivation | It still holds the old key | update-access-key --status Active on the old key, update that consumer, then deactivate again |
LimitExceeded on create | User already has two keys | Delete an inactive or unused key first; if both are active, rotate one of them first |
| New secret lost | Secret not saved at creation | Deactivate and delete the new key and create another; secrets cannot be retrieved later |
| Old key still shows recent use days later | A cached credential or an unknown consumer | Use CloudTrail source IP and user agent to locate it; do not deactivate until found |
| Old key deleted too early | Skipped the inactive period | No undo. Give the consumer the current key from the secret store |
| Third party cannot rotate quickly | Key embedded in a supplier platform | Agree a rotation window with the supplier and keep both keys active only for that window |
Hardening afterwards
- Remove the key where you can: AWS recommends temporary credentials through IAM roles. Workloads on AWS compute should use instance or task roles; external CI and other clouds can use OIDC federation; on-premises servers can use IAM Roles Anywhere. See the Workload Identity Federation Guide and the AWS IAM Roles Anywhere Security Guide.
- One consumer per key: a key shared by five systems needs five coordinated changes. Split it into one IAM user (or better, one role) per consumer so rotation and revocation are independent.
- Tag and document: use the access key description tag to record the consumer and owner so the next rotation starts with a known list.
- Enforce age: deploy
access-keys-rotatedwith amaxAccessKeyAgethat matches your policy, in a Region where the rule is available, since it evaluates global IAM resources. - Clean up dormant keys: rotation is the moment to ask whether the user is needed at all. See the sibling runbook How to find unused AWS IAM roles and access keys.
Choosing a rotation approach
| Approach | Best for | Trade-off |
|---|---|---|
| Manual overlap (this guide) | A small number of keys with known owners | Human effort per key; easy to skip the waiting period |
| Scripted overlap through a secret store | Many keys with consumers that reload from the store | Consumers must reload without restart, or the script must restart them |
| Replace with role-based temporary credentials | Anything that can assume a role | One-off migration effort; no rotation needed afterwards |
Small teams with a handful of keys should go straight to removing them in favour of roles. Large estates should measure: percentage of active keys older than policy age, number of IAM users with two active keys outside a rotation window, and median days from rotation start to old key deletion. Keys that cannot be removed should be few, owned and tagged.
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev 5 | IA-5 Authenticator Management | Changing authenticators periodically and on compromise |
| NIST SP 800-53 Rev 5 | AC-2 Account Management | Owner and purpose for each IAM user |
| NIST CSF 2.0 | PR.AA-01 | Credentials for services are managed by the organisation |
| MITRE ATT&CK | T1078.004 Cloud Accounts; T1552.001 Credentials In Files | Shortens the useful life of keys stolen from files or repositories |
Practitioner checklist
- Confirm the key is not known to be leaked; if it is, use the leak playbook instead.
- Check the user has a free key slot with
list-access-keys. - Build the consumer list from last-used data, CloudTrail by AccessKeyId and the owner.
- Create the new key and write the secret straight into the secret store.
- Restart or reload every consumer and confirm the new key shows use.
- Wait several days, then deactivate the old key, never delete first.
- Delete after a quiet inactive period and confirm the Config rule is compliant.
- Record a plan to replace the key with a role.
Standards and references
- AWS: Update access keys (IAM User Guide)
- AWS: Manage access keys for IAM users
- AWS CLI Reference: get-access-key-last-used
- AWS: Generate credential reports
- AWS CLI Reference: cloudtrail lookup-events
- AWS: CloudTrail userIdentity element
- AWS Config: access-keys-rotated managed rule
Related NHI Mgmt Group resources: AWS Access Keys Security Guide · Cloud Access Key Leak Playbook · How to find unused AWS IAM roles and access keys · Workload Identity Federation Guide