How to rotate access keys used by applications

Topic: Accounts access

Safely rotate IAM access keys used by applications and automation: create a second key, update all consumers, verify they use the new key, then deactivate and delete the old key. Use this on a schedule or when a key may be compromised; prefer migrating to IAM roles to avoid long-lived keys.

Intent: How-to

Quick answer

  • Create a new access key for the IAM user the app uses; do not delete the old key yet. Update every consumer (config, secrets manager, CI, scripts) to use the new key.
  • Verify each consumer works with the new key (run a test job or API call); then deactivate the old key and monitor for errors before deleting it.
  • Run rotation on a schedule (e.g. 90 days) and document where each key is used; prefer migrating apps to IAM roles so rotation is not needed (see migration guide).

Prerequisites

Steps

  1. Identify all consumers of the key

    List systems that use the IAM user's access key: CI/CD, scripts, on-prem apps, cloud config, secrets managers; document each so you can update them during rotation.

  2. Create a new access key

    Create a second access key for the IAM user (create-access-key); store the secret securely and do not delete the existing key yet—you can have up to two active keys per user.

  3. Update consumers and verify

    Update each consumer to use the new key (environment variables, config files, secrets manager); run a test for each (e.g. aws sts get-caller-identity or the app's API call) to confirm success.

  4. Deactivate and delete the old key

    Deactivate the old key with update-access-key --status Inactive; monitor logs and jobs for a short period; if no errors, delete the old key with delete-access-key.

Summary

You will rotate access keys used by applications by creating a new key, updating all consumers to use it, verifying they work, then deactivating and deleting the old key. Use this on a schedule or when compromise is suspected; for new apps, prefer IAM roles so keys are not needed (see migration guide).

Prerequisites

  • IAM user that has access keys used by one or more applications (see How to create and rotate IAM user access keys).
  • IAM permission to create and delete access keys for that user; list of all systems that use the key (CI, scripts, config, secrets manager).

Steps

Step 1: Identify all consumers of the key

  • Search code and config for the access key ID (e.g. AKIA…) or the IAM user name; check CI/CD variables, secrets managers (AWS Secrets Manager, HashiCorp Vault), and deployment configs.
  • Document each consumer (e.g. “GitHub Actions prod deploy”, “on-prem backup script”, “app config in S3”) so you can update and test each during rotation.

Step 2: Create a new access key

aws iam create-access-key --user-name APP_USER

Save the returned AccessKeyId and SecretAccessKey securely. You can have at most two active keys per user, so the old key remains active until you delete it. Do not delete the old key until all consumers are on the new key and verified.

Step 3: Update consumers and verify

  • Update each consumer with the new AccessKeyId and SecretAccessKey (env vars, config, secrets manager). Prefer a secrets manager so you update in one place and apps pull at runtime.
  • For each consumer, run a test: e.g. aws sts get-caller-identity with the new credentials, or trigger the app’s normal AWS call (e.g. S3 list, deploy job). Confirm no AccessDenied or invalid key errors.

Step 4: Deactivate and delete the old key

  1. Deactivate the old key so it can no longer be used: 
    aws iam update-access-key --user-name APP_USER --access-key-id OLD_KEY_ID --status Inactive
  2. Monitor application logs and CI jobs for a few hours or days. Any system still using the old key will start failing; fix those to use the new key.
  3. When you are confident no consumer uses the old key, delete it: 
    aws iam delete-access-key --user-name APP_USER --access-key-id OLD_KEY_ID

Verification

  • All documented consumers use the new key and tests pass.
  • The old key is Inactive and then deleted; list-access-keys shows only one (or two if you keep a spare) key for the user.
  • No applications or jobs fail with invalid key or access denied after rotation.

Troubleshooting

Consumer still using old key after rotation — Find the consumer (check error logs for key ID or user); update its config or secrets to the new key. Do not delete the old key until all consumers are updated; use the deactivate step to surface stragglers.

Cannot create second key (limit 2) — You already have two active keys. Deactivate and delete one, or complete rotation by moving all consumers to one key and deleting the other, then create the new key.

Secret lost for new key — You cannot retrieve the secret after creation. Create another new key, update consumers to it, then delete both old keys (the one you were rotating to and the original).

Next steps

Continue to