DEV Community

Himanshu Maheshwari
Himanshu Maheshwari

Posted on

Managing Multiple AWS Accounts Like a Pro: A Complete Guide

#aws #cloudcomputing #developers #devops

Imagine you have multiple email accounts - one for work, one personal, and maybe one for side projects. You switch between them throughout the day without any hassle. AWS accounts work the same way!

As developers, we often juggle multiple AWS accounts:

  • 🏢 Company account for work projects
  • 👤 Personal account for side projects
  • 💼 Client accounts for freelance work
  • 🧪 Separate accounts for development and production

Switching between these accounts shouldn't be complicated. In this guide, I'll show you exactly how to manage multiple AWS accounts on a single machine, making it as easy as switching browser tabs.

Why Multiple AWS Accounts?

Before we dive in, let's understand why you might need multiple accounts:

Separation of Concerns

  • Keep work and personal projects separate
  • Avoid accidental changes to the wrong environment
  • Separate billing for different projects

Security & Isolation

  • Limit the blast radius if credentials are compromised
  • Different security requirements for different projects
  • Client data stays in client accounts

Cost Management

  • Track costs per project or client
  • Separate billing for better accounting
  • Avoid surprise bills mixing personal and work usage

The AWS Credentials Setup

Understanding the File Structure

AWS stores your credentials in two files on your computer:

  1. ~/.aws/credentials - Contains your access keys (the passwords)
  2. ~/.aws/config - Contains configuration settings (regions, output formats)

Think of it like this:

  • credentials = Your passport (proves who you are)
  • config = Your travel preferences (where you want to go, how you want to travel)

The Credentials File

Here's what a typical ~/.aws/credentials file looks like:

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[work-project]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

[personal]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[client-xyz]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Enter fullscreen mode Exit fullscreen mode

Important Security Notes:

  • ⚠️ Never share these credentials with anyone
  • ⚠️ Never commit them to Git or GitHub
  • ⚠️ Rotate them regularly (every 90 days recommended)
  • ⚠️ The keys shown above are fake examples only

The Config File

Create or edit ~/.aws/config:

[default]
region = us-east-1
output = json

[profile work-project]
region = us-west-2
output = json

[profile personal]
region = eu-west-1
output = json

[profile client-xyz]
region = ap-southeast-1
output = table
Enter fullscreen mode Exit fullscreen mode

Important: In the config file, profile names need the profile prefix (except for default).

Step-by-Step: Setting Up Multiple Profiles

Step 1: Check Your Current AWS Account

Before making changes, let's see which account you're currently using:

aws sts get-caller-identity
Enter fullscreen mode Exit fullscreen mode

This command shows you:

{
  "UserId": "AIDAI23HXD2WQ4EXAMPLE",
  "Account": "123456789012",
  "Arn": "arn:aws:iam::123456789012:user/johndoe"
}
Enter fullscreen mode Exit fullscreen mode

Translation:

  • UserId: Your unique user ID in AWS
  • Account: The AWS account number you're connected to
  • Arn: Your full AWS identity path

Step 2: Create a New Profile

Let's add a new AWS account profile:

aws configure --profile my-new-project
Enter fullscreen mode Exit fullscreen mode

You'll be prompted for:

AWS Access Key ID [None]: AKIAI44QH8DHBEXAMPLE
AWS Secret Access Key [None]: je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json
Enter fullscreen mode Exit fullscreen mode

Where to get these values:

  1. Log into AWS Console
  2. Go to IAM → Users → Your User
  3. Click "Security credentials" tab
  4. Click "Create access key"
  5. Save the Access Key ID and Secret Access Key

Step 3: Verify the New Profile

Test that your new profile works:

aws sts get-caller-identity --profile my-new-project
Enter fullscreen mode Exit fullscreen mode

If you see account information, you're all set! 🎉

Switching Between AWS Accounts

Now that you have multiple profiles, here are three ways to switch between them:

Method 1: Set Profile for Your Entire Terminal Session 

# Switch to work-project account
export AWS_PROFILE=work-project

# Verify the switch
aws sts get-caller-identity

# All subsequent commands use work-project
aws s3 ls
aws ec2 describe-instances
aws lambda list-functions
Enter fullscreen mode Exit fullscreen mode

Use case: You're working on one project for several hours.

Tip: To see which profile you're using:

echo $AWS_PROFILE
Enter fullscreen mode Exit fullscreen mode

To switch back to default:

unset AWS_PROFILE
Enter fullscreen mode Exit fullscreen mode

Method 2: One-Time Use for a Single Command 

# Use work-project for this command only
aws s3 ls --profile work-project

# Use personal for this command only
aws s3 ls --profile personal

# Use client-xyz for this command only
aws ec2 describe-instances --profile client-xyz
Enter fullscreen mode Exit fullscreen mode

Use case: You need to quickly check something in another account without switching your entire session.

Method 3: Automatic Switching Based on Folder (The Smart Way!)

This is the most convenient method for developers working on multiple projects.

Install direnv (auto-loads environment variables per folder):

# Install on macOS
brew install direnv

# Install on Linux
sudo apt-get install direnv

# Add to your shell configuration
# For zsh (~/.zshrc):
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

# For bash (~/.bashrc):
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

# Reload your shell
source ~/.zshrc  # or source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

Set up automatic profile switching:

Create a .envrc file in your project folder:

# Navigate to your work project
cd ~/projects/work-app

# Create .envrc file
cat > .envrc << 'EOF'
export AWS_PROFILE=work-project
export AWS_REGION=us-west-2
EOF

# Allow direnv to load this file
direnv allow
Enter fullscreen mode Exit fullscreen mode

Now, every time you cd into this folder, it automatically uses the work-project profile!

Set it up for all your projects:

# Work project
cd ~/projects/work-app
echo "export AWS_PROFILE=work-project" > .envrc
direnv allow

# Personal project
cd ~/projects/my-blog
echo "export AWS_PROFILE=personal" > .envrc
direnv allow

# Client project
cd ~/freelance/client-xyz
echo "export AWS_PROFILE=client-xyz" > .envrc
direnv allow
Enter fullscreen mode Exit fullscreen mode

How it works:

# You're using default profile
aws sts get-caller-identity
# Shows default account

cd ~/projects/work-app
# direnv automatically sets AWS_PROFILE=work-project
aws sts get-caller-identity
# Shows work account!

cd ~/projects/my-blog
# direnv automatically sets AWS_PROFILE=personal
aws sts get-caller-identity
# Shows personal account!
Enter fullscreen mode Exit fullscreen mode

Visual Indicator in Your Terminal

Want to always see which AWS profile you're using? Add this to your terminal prompt!

For Zsh (~/.zshrc) 

# Function to show current AWS profile
aws_profile() {
  if [ -n "$AWS_PROFILE" ]; then
    echo "☁️ [$AWS_PROFILE]"
  fi
}

# Add to your prompt
setopt PROMPT_SUBST
PS1='$(aws_profile) '$PS1
Enter fullscreen mode Exit fullscreen mode

For Bash (~/.bashrc) 

# Function to show current AWS profile
aws_profile() {
  if [ -n "$AWS_PROFILE" ]; then
    echo "☁️ [$AWS_PROFILE]"
  fi
}

# Add to your prompt
PS1='$(aws_profile) '$PS1
Enter fullscreen mode Exit fullscreen mode

Reload your shell:

source ~/.zshrc  # or source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

Your terminal will now show:

☁️ [work-project] mahesh@macbook ~/projects/work-app %
Enter fullscreen mode Exit fullscreen mode

When you're not using a specific profile, the cloud icon disappears.

Managing Your Profiles

List All Configured Profiles 

aws configure list-profiles
Enter fullscreen mode Exit fullscreen mode

Output:

default
work-project
personal
client-xyz
Enter fullscreen mode Exit fullscreen mode

View Configuration for a Specific Profile 

# See all settings
aws configure list --profile work-project

# Get specific setting
aws configure get region --profile work-project
aws configure get output --profile work-project
Enter fullscreen mode Exit fullscreen mode

Update a Profile Setting 

# Change region
aws configure set region us-east-1 --profile work-project

# Change output format
aws configure set output table --profile personal
Enter fullscreen mode Exit fullscreen mode

Test Profile Credentials 

# Test if credentials work
aws sts get-caller-identity --profile work-project

# List S3 buckets to verify access
aws s3 ls --profile work-project

# Check which region is configured
aws configure get region --profile work-project
Enter fullscreen mode Exit fullscreen mode

Real-World Workflow Example

Let's say you're working on three different projects in a day:

Morning: Work Project (Company Account) 

cd ~/projects/company-app
# direnv automatically sets AWS_PROFILE=work-project

# Deploy to work infrastructure
aws s3 sync ./build s3://company-website-bucket
aws cloudfront create-invalidation --distribution-id E123456 --paths "/*"

# Check logs
aws logs tail /aws/lambda/company-function --follow
Enter fullscreen mode Exit fullscreen mode

Afternoon: Personal Blog (Personal Account) 

cd ~/projects/my-blog
# direnv automatically sets AWS_PROFILE=personal

# Deploy your blog
aws s3 sync ./public s3://my-personal-blog
aws cloudfront create-invalidation --distribution-id E789012 --paths "/*"

# Check visitor stats
aws cloudwatch get-metric-statistics --namespace AWS/S3 \
  --metric-name NumberOfObjects --dimensions Name=BucketName,Value=my-personal-blog \
  --statistics Average --start-time 2024-01-01T00:00:00Z --end-time 2024-01-31T23:59:59Z \
  --period 86400
Enter fullscreen mode Exit fullscreen mode

Evening: Client Work (Client Account) 

cd ~/freelance/client-xyz
# direnv automatically sets AWS_PROFILE=client-xyz

# Deploy client application
aws ecs update-service --cluster client-cluster --service client-app \
  --force-new-deployment

# Check deployment status
aws ecs describe-services --cluster client-cluster --services client-app
Enter fullscreen mode Exit fullscreen mode

Notice: You never had to manually switch profiles! Each folder automatically uses the correct account.

Best Practices

1. Never Commit Credentials to Git

Always add these to your .gitignore:

# AWS Credentials
.env
.envrc
.aws/credentials
.aws/config
*.pem
*.key

# Environment files
.env.local
.env.production
Enter fullscreen mode Exit fullscreen mode

2. Use Meaningful Profile Names

Bad ❌:

profile1
profile2
test
prod
Enter fullscreen mode Exit fullscreen mode

Good ✅:

company-production
company-development
personal-projects
client-acme-prod
client-acme-dev
startup-staging
Enter fullscreen mode Exit fullscreen mode

3. Document Profile Usage

Add to your project's README.md:

## AWS Configuration

This project uses the `work-project` AWS profile.

### Setup

1. Configure the AWS profile:
Enter fullscreen mode Exit fullscreen mode


bash
aws configure --profile work-project


2. Set environment variables:
Enter fullscreen mode Exit fullscreen mode


bash
export AWS_PROFILE=work-project
export AWS_REGION=us-west-2


3. Verify setup:
Enter fullscreen mode Exit fullscreen mode


bash
aws sts get-caller-identity


### Required Permissions

This project requires access to:
- S3 bucket: `company-assets`
- Lambda functions: `company-api-*`
- CloudFront distribution: `E123456`
Enter fullscreen mode Exit fullscreen mode

4. Create Helper Scripts

Create ~/bin/aws-switch.sh:

#!/bin/bash

echo "🌥️  AWS Profile Switcher"
echo "======================="
echo ""
echo "Available profiles:"
aws configure list-profiles | nl

echo ""
read -p "Enter profile name: " profile_name

export AWS_PROFILE=$profile_name
echo ""
echo "✅ Switched to: $AWS_PROFILE"
echo ""
aws sts get-caller-identity
Enter fullscreen mode Exit fullscreen mode

Make it executable:

chmod +x ~/bin/aws-switch.sh
Enter fullscreen mode Exit fullscreen mode

Use it:

~/bin/aws-switch.sh
Enter fullscreen mode Exit fullscreen mode

5. Rotate Access Keys Regularly 

# Create new access key (do this in AWS Console)
# Then update your credentials file

# Test new credentials
aws sts get-caller-identity --profile work-project

# If working, delete old access key in AWS Console
Enter fullscreen mode Exit fullscreen mode

Set a calendar reminder to rotate keys every 90 days.

Troubleshooting Common Issues

Issue 1: "Unable to locate credentials"

Symptoms:

Unable to locate credentials. You can configure credentials by running "aws configure".
Enter fullscreen mode Exit fullscreen mode

Solutions:

# Check if credentials file exists
ls -la ~/.aws/credentials

# Check if profile exists
aws configure list-profiles

# Verify profile name matches
echo $AWS_PROFILE

# Re-configure if needed
aws configure --profile work-project
Enter fullscreen mode Exit fullscreen mode

Issue 2: "Access Denied" Errors

Symptoms:

An error occurred (AccessDenied) when calling the ListBuckets operation: Access Denied
Enter fullscreen mode Exit fullscreen mode

Solutions:

# Verify you're using the correct profile
aws sts get-caller-identity

# Check if credentials are valid
aws sts get-caller-identity --profile work-project

# If invalid, create new access keys and update credentials file
Enter fullscreen mode Exit fullscreen mode

Issue 3: Wrong Region Being Used

Symptoms:

Could not connect to the endpoint URL: "https://s3.us-west-2.amazonaws.com/my-bucket"
Enter fullscreen mode Exit fullscreen mode

Solutions:

# Check current region
aws configure get region --profile work-project

# Set correct region
aws configure set region us-east-1 --profile work-project

# Or set via environment variable
export AWS_REGION=us-east-1
Enter fullscreen mode Exit fullscreen mode

Issue 4: direnv Not Working

Symptoms:
.envrc file exists but profile not switching automatically

Solutions:

# Check if direnv is installed
which direnv

# Check if direnv hook is in your shell config
cat ~/.zshrc | grep direnv

# If missing, add it
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
source ~/.zshrc

# Allow direnv in your project
cd /path/to/project
direnv allow
Enter fullscreen mode Exit fullscreen mode

Advanced: Using AWS SSO (Single Sign-On)

If your company uses AWS SSO, here's how to set it up:

Configure SSO Profile 

aws configure sso
Enter fullscreen mode Exit fullscreen mode

Follow the prompts:

SSO start URL [None]: https://my-company.awsapps.com/start
SSO Region [None]: us-east-1
SSO registration scopes [None]: sso:account:access
Enter fullscreen mode Exit fullscreen mode

Your browser will open for authentication.

Use SSO Profile 

# Login to SSO
aws sso login --profile company-sso

# Use the profile
export AWS_PROFILE=company-sso
aws s3 ls

# Session expires after a few hours, re-login with:
aws sso login --profile company-sso
Enter fullscreen mode Exit fullscreen mode

Auto-refresh SSO Sessions

Add to your ~/.zshrc:

# Auto-refresh AWS SSO session
aws_sso_refresh() {
  if [ -n "$AWS_PROFILE" ]; then
    aws sso login --profile $AWS_PROFILE 2>/dev/null
  fi
}

# Run before each command (optional)
# precmd() { aws_sso_refresh }
Enter fullscreen mode Exit fullscreen mode

Quick Reference Cheat Sheet 

# List all profiles
aws configure list-profiles

# Check current account
aws sts get-caller-identity

# Check current profile
echo $AWS_PROFILE

# Set profile for session
export AWS_PROFILE=work-project

# Unset profile (back to default)
unset AWS_PROFILE

# Use profile for single command
aws s3 ls --profile personal

# Configure new profile
aws configure --profile new-project

# Test profile credentials
aws sts get-caller-identity --profile work-project

# Get profile configuration
aws configure list --profile work-project

# Set specific configuration
aws configure set region us-east-1 --profile work-project

# Get specific configuration
aws configure get region --profile work-project
Enter fullscreen mode Exit fullscreen mode

Understanding Credential Priority

AWS looks for credentials in this order:

  1. Command line options (--profile)
  2. Environment variables (AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
  3. Credentials file (~/.aws/credentials)
  4. Config file (~/.aws/config)
  5. IAM role (when running on EC2, ECS, Lambda)

Example:

# Even if AWS_PROFILE=personal is set
export AWS_PROFILE=personal

# This command uses work-project (command line wins)
aws s3 ls --profile work-project
Enter fullscreen mode Exit fullscreen mode

Conclusion

Managing multiple AWS accounts doesn't have to be complicated. With proper setup:

✅ Switch between accounts seamlessly

✅ Automate profile selection per project

✅ See which account you're using at a glance

✅ Keep credentials secure and organized

✅ Never accidentally work in the wrong account

Key Takeaways:

  1. Use named profiles for different AWS accounts
  2. Use direnv for automatic profile switching per project
  3. Add visual indicators to your terminal prompt
  4. Never commit credentials to version control
  5. Rotate access keys every 90 days
  6. Document which profile each project uses
  7. Test credentials regularly

Recommended Setup: 

# 1. Install direnv
brew install direnv

# 2. Add to shell
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

# 3. Add profile indicator to prompt
echo 'aws_profile() { [ -n "$AWS_PROFILE" ] && echo "☁️ [$AWS_PROFILE]"; }' >> ~/.zshrc
echo 'setopt PROMPT_SUBST' >> ~/.zshrc
echo 'PS1='"'"'$(aws_profile) '"'"'$PS1' >> ~/.zshrc

# 4. Reload shell
source ~/.zshrc

# 5. Set up project folders with .envrc
cd ~/projects/work-app
echo "export AWS_PROFILE=work-project" > .envrc
direnv allow
Enter fullscreen mode Exit fullscreen mode

Remember: Organization leads to productivity. Spend 30 minutes setting this up, and you'll save hours of frustration and prevent costly mistakes!

Additional Resources

Pro Tip: Consider using AWS Vault for even better security - it stores your credentials in your system's encrypted keychain instead of plain text files!

Happy cloud computing! ☁️

Top comments (0)