Typical use-cases

Typical use-cases for aws-vault

There are a few different ways aws-vault can be used

Use-case 1: aws-vault is the executor and provides the environment

Use aws-vault exclusively as a command executor, where aws-vault provides the environment and runs a command.

; master creds added with 'aws-vault add my_profile_master'
[profile my_profile_master]

[profile my_profile_role]
source_profile=my_profile_master
role_arn=xxx

aws-vault exec my_profile_master ./my-command   # success, uses sts session generated by aws-vault
aws-vault exec my_profile_role ./my-command     # success, uses role creds generated by aws-vault

AWS_PROFILE=my_profile_master ./my-command      # Not expected to be functional
AWS_PROFILE=my_profile_role ./my-command        # Not expected to be functional

In this scenario, the profile name and aws config is used exclusively by aws-vault, which provides the environment for the command to run in.

This is a very unix-y and 12-factor approach. It’s the original and the primary use-case of aws-vault - it’s why aws-vault exec exists.

Use-case 2: aws-vault is a “master credentials vault” for AWS SDK

aws-vault can be used in credential_process in the AWS config to provide master creds. This is more in-line with the AWS SDK way of approaching the problem via credential_process and AWS_PROFILE

; master creds added with 'aws-vault add my_profile_master'
[profile my_profile_master]
credential_process = aws-vault export --format=json --no-session my_profile_master

[profile my_profile_role]
source_profile=my_profile_master
role_arn=xxx

aws-vault exec my_profile_master ./my-command   # success (uses master creds)
aws-vault exec my_profile_role ./my-command     # success (aws-vault role)

AWS_PROFILE=my_profile_master ./my-command      # success (uses credential_process to get aws-vault master creds)
AWS_PROFILE=my_profile_role ./my-command       # success (SDK role)

Use-case 3: aws-vault is a “MFA session cache” for AWS SDK

Very similar to Use-case 2, aws-vault can be used to cache STS MFA credentials between profiles. This means you are not forced to re-authenticate with MFA every time you switch profiles

; master creds added with 'aws-vault add my_profile_master'
[profile my_profile_master]
mfa_serial=mmm
credential_process = aws-vault export --format=json my_profile_master

[profile my_profile_role]
source_profile=my_profile_master
mfa_serial=mmm
role_arn=xxx1

[profile my_profile_role2]
source_profile=my_profile_master
mfa_serial=mmm
role_arn=xxx2

aws-vault exec my_profile_master ./my-command   # success (STS session)
aws-vault exec my_profile_role ./my-command     # success (role)

AWS_PROFILE=my_profile_master ./my-command      # success (uses credential_process to get aws-vault session)
AWS_PROFILE=my_profile_role ./my-command        # success (uses aws-vault session + SDK role)

Use-case 4: aws-vault caches alternative credential sources

aws-vault caches credentials from alternative credential sources like sso_start_url, web_identity_token_process, credential_process

[profile my_profile_using_sso]
sso_start_url = https://mycompany.awsapps.com/start

[profile my_profile_using_process]
credential_process = my-custom-creds-cmd

aws-vault exec my_profile_using_sso ./my-command       # success, uses aws-vault caching
aws-vault exec my_profile_using_process ./my-command   # success, uses aws-vault caching

AWS_PROFILE=my_profile_using_sso ./my-command          # success, no caching
AWS_PROFILE=my_profile_using_process ./my-command      # success, no caching

Last updated on August 5, 2026

Getting Help Config