AWS CLI named profiles: switching between IAM users without hitting the wrong account

It's normal to work with more than one AWS IAM user: a sandbox and a client account, a personal and a company account, or a read-only user and a deploy user. The AWS CLI handles this with named profiles. When a command runs against the wrong account, it's rarely anything mysterious in AWS. Usually it's the wrong profile, leftover environment variables, or the Console and the CLI looking at different accounts or regions.

The idea is simple: each IAM user gets one access key pair and one named profile. You choose the profile with AWS_PROFILE or --profile, then check it with aws sts get-caller-identity.

Region is set separately, so check that too.

Why profiles exist

Every CLI call needs three things:

1. Who you are: an IAM user or role.
2. Which account: the 12-digit account ID.
3. Which region: for example, ap-southeast-1.

IAM users belong to an account, and each user can have access keys. Don't share those keys, and don't overwrite one global set of credentials every time you switch work.

A profile is a named set of credentials plus optional defaults, such as region and output format. You choose a profile for a whole shell session or for a single command, and the CLI signs each request as that identity.

Naming the profile after the IAM user makes it obvious who you are when you run echo $AWS_PROFILE late at night.

The two files in ~/.aws

credentials: secrets only

The section name is the profile name, with no profile prefix.

[default]
aws_access_key_id = AKIA................
aws_secret_access_key = ........................................

[client_deploy]
aws_access_key_id = AKIA................
aws_secret_access_key = ........................................

config: everything else

This file holds the region, output format, SSO settings, and role settings. Named profiles need the profile prefix here, but default doesn't.

[default]
region = ap-southeast-1
output = json

[profile client_deploy]
region = ap-southeast-1
output = json

[profile alice_admin]
region = us-east-1
output = json

Keep the credentials file private (chmod 600 is a good habit). Never commit either file to git, and never paste secrets into tickets or chat.

Creating a profile for a new IAM user

1. Sign in to the Console for the right account. Go to IAM, then Users, and create the user with only the permissions it needs. On the user's Security credentials tab, create an access key and choose the CLI use case. Save the secret right away, because AWS only shows it once.
2. On your laptop, run:

aws configure --profile client_deploy

Enter the key, the secret, the region, and the output format. This writes to both files.

3. Check that it worked:

aws configure list-profiles
aws configure list --profile client_deploy

Choosing which user to act as

For a whole session

export AWS_PROFILE=client_deploy
echo "$AWS_PROFILE"

Every aws command in that shell uses this profile until you change or unset it.

unset AWS_PROFILE

Once it's unset, the CLI goes back to the default profile, if you have one.

For one command

aws s3 ls --profile client_deploy
aws ec2 describe-instances --profile alice_admin --region us-east-1

In two terminals

You can keep a different profile in each terminal. AWS_PROFILE only applies to the shell where you set it, so they don't affect each other.

The command to run all the time

aws sts get-caller-identity

{
  "UserId": "AIDAEXAMPLEID",
  "Account": "111122223333",
  "Arn": "arn:aws:iam::111122223333:user/client_deploy"
}

Shorter versions:

aws sts get-caller-identity --query Arn --output text
aws sts get-caller-identity --query Account --output text
aws sts get-caller-identity --profile client_deploy

Make it a habit: before you delete anything, push an image, or change a security group, run get-caller-identity and check both the user and the account.

Which credentials win when several are set

The CLI looks for credentials in this order and uses the first ones it finds:

1. The --profile option on the command itself.
2. The environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, plus AWS_SESSION_TOKEN if it's set.
3. The profile named in AWS_PROFILE (or the older AWS_DEFAULT_PROFILE), or default if neither is set. That includes access keys in the credentials file and any SSO or assume-role settings in the config file.
4. On AWS itself, credentials from the container or the EC2 instance role.

See the AWS CLI documentation on configuration precedence for the full list.

The trap: leftover access keys in your environment

Say you once ran:

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

Those keys take priority over AWS_PROFILE. You think you switched users, but you didn't. (Passing --profile on the command does override them, which makes the bug even more confusing.)

To fix it:

unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
export AWS_PROFILE=client_deploy
aws sts get-caller-identity
aws configure list

aws configure list shows whether the keys and region come from environment variables or from a file. Run it whenever something doesn't add up.

Region is separate from identity

There are three ways to set it:

1. In the profile's block in ~/.aws/config.
2. With export AWS_REGION=ap-southeast-1 (or AWS_DEFAULT_REGION).
3. With --region ap-southeast-1 on a single command.

export AWS_PROFILE=client_deploy
export AWS_REGION=ap-southeast-1
aws ec2 describe-instances

The Console and the CLI need to match on both account and region. For example, resources in Singapore won't show up if the Console's region menu is still set to N. Virginia.

A typical day

Start:

export AWS_PROFILE=client_deploy
export AWS_REGION=ap-southeast-1
aws sts get-caller-identity

Switch:

export AWS_PROFILE=alice_admin
aws sts get-caller-identity

Run one command without changing the session:

aws iam list-users --profile alice_admin

Clean up at the end (optional):

unset AWS_PROFILE
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

Working across accounts

Changing the region doesn't move an IAM user from account 111111111111 to account 222222222222. Each profile points to the keys of one user in one specific account.

To work in two accounts, you usually have one of these:

• Two IAM users, with one profile each.
• One user who assumes a role in the other account, set up with role_arn and source_profile in the config file.

For most laptops that juggle several clients, one profile per IAM user is the simplest setup.

Where this causes real problems: Docker and ECR

Each ECR registry belongs to one account:

<ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com

Log in with a user that has push access to that account's registry. Usually that's a user in the same account:

export AWS_PROFILE=client_deploy

ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REGION=ap-southeast-1

aws ecr get-login-password --region "$REGION" \
  | docker login --username AWS --password-stdin \
    "${ACCOUNT}.dkr.ecr.${REGION}.amazonaws.com"

If you log in with a profile for account A and then push to account B's registry, the push fails with an authorization error or "no basic auth credentials". These errors look like Docker problems, but the real cause is that the accounts don't match.

Make sure these three agree:

1. AWS_PROFILE
2. The account ID from sts get-caller-identity
3. The account ID in the ECR hostname

When something is "missing" in the Console

The account and the region have to match. Using the right profile in the CLI won't help if the browser is still signed in to a different account.

Security habits worth keeping

1. Use named profiles for anything important. Leave default empty, use it only for a sandbox, or make it obvious what it's for.
2. Give each person their own keys. Never share access keys.
3. Rotate a key if it ever appears in chat, a screenshot, a ticket, or git history.
4. Never commit ~/.aws/credentials.
5. Give each IAM user only the permissions it needs. Separate deploy users from read-only users when that helps.
6. Use IAM Identity Center (SSO) or other temporary credentials when your organization supports them. AWS recommends them over long-lived access keys, and they work with the same profile setup.

Optional: SSO profiles

aws configure sso --profile company_devops
aws sso login --profile company_devops
export AWS_PROFILE=company_devops
aws sts get-caller-identity

You still switch with AWS_PROFILE. The only difference is how the credentials are obtained.

Troubleshooting

Cheat sheet

aws configure --profile MY_USER
aws configure list-profiles

export AWS_PROFILE=MY_USER
export AWS_REGION=ap-southeast-1
aws sts get-caller-identity

aws s3 ls --profile OTHER_USER

unset AWS_PROFILE
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
aws configure list

Summary

Working with several AWS users stays painless when you switch identity on purpose instead of trusting whatever is set. Check who you are before anything that creates, deletes, or pushes. Most confusing failures come down to the wrong profile, leftover environment keys, or the Console and CLI using different accounts or regions.

For more on AWS costs, see AWS cost floors: ALB, NAT, ECS Express Mode, and free-tier traps.