Skip to main content

ROTATE AN IAM USER ACCESS KEY INTO A SWAMP VAULT

This guide shows you how to rotate the access key of an IAM user with @sntxrr/aws-access-key. The new key goes into a Swamp vault item. Consumers then move to it, and the old key is deactivated and finally deleted. The example user is ci-deployer.

Prerequisites

  • A vault named ci-keys in the repository (see Vaults)
  • AWS credentials allowed to list, create, update and delete access keys for the user

Pull the extension

swamp extension pull @sntxrr/aws-access-key

The output looks like:

INF extension·pull: Pulling "@swamp/aws/iam"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/aws/iam"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/aws/iam"@"2026.10.13.1"
INF extension·pull: Extracted 30 files:

Define the key behavior

Create a behavior named ci-deployer-keys of type @sntxrr/aws-access-key (see Create and Run a Behavior). userName is required. targetVault and targetItem tell create where to write the new key:

globalArguments:
  userName: ci-deployer
  targetVault: ci-keys
  targetItem: ci-deployer

Record the current keys

swamp behavior run ci-deployer-keys list

This command reads the user's access keys from AWS and writes an inventory resource. The inventory records each key's status, age and last use. Note the ID of the key you are replacing.

Mint the new key into the vault

swamp behavior run ci-deployer-keys create --input 'allowSecond:json=true'

This command creates a new access key for ci-deployer and writes it to ci-keys as ci-deployer/access-key-id and ci-deployer/secret-access-key. It reads both values back to confirm the write, and records the key's metadata, but never the secret, as a key resource. If the vault write fails, the new key is rolled back. allowSecond lets create run while the old key still exists.

Check the vault

swamp vault list-keys ci-keys

This command lists the key names stored in ci-keys. The list should include ci-deployer/access-key-id and ci-deployer/secret-access-key.

Move consumers to the new key

In every behavior that authenticates as ci-deployer, point the credentials at the vault item:

globalArguments:
  accessKeyId: "${{ vault.get('ci-keys', 'ci-deployer/access-key-id') }}"
  secretAccessKey: "${{ vault.get('ci-keys', 'ci-deployer/secret-access-key') }}"

If a consumer outside Swamp also uses the key, update it as well before you continue.

Deactivate the old key

Replace AKIAOLDKEYEXAMPLE with the ID you noted from list:

swamp behavior run ci-deployer-keys deactivate --input accessKeyId=AKIAOLDKEYEXAMPLE

This command sets the old key to Inactive in AWS. You can reverse this step. Watch for failures in anything that used the old key, and run list again to check that its last use has stopped changing.

Delete the old key

swamp behavior run ci-deployer-keys delete --input accessKeyId=AKIAOLDKEYEXAMPLE

This command deletes the old key from AWS. It will not delete a key that is still Active, so deactivate the key first.

Refer to the extensions reference for the full set of arguments and methods. To refresh short-lived cloud credentials automatically instead, see Auto-Refresh Cloud Credentials.