Named Profiles & Multi-Account Config

Named profiles let one machine hold many AWS identities - separate accounts, separate roles - and switch between them by name.

Summary

A named profile is a labeled block of settings in the shared AWS files. Each profile is an independent identity.

Most real work spans more than one account: a dev account, a staging account, a production account. Profiles keep those identities side by side without re-running aws configure every time.

The layout is split across two files. Long-lived secrets go in ~/.aws/credentials. Everything else - region, output, role assumption, SSO - goes in ~/.aws/config.

The same profiles are visible to the CLI, boto3, and the AWS SDK for JavaScript v3. Configure once, use everywhere.

A common advanced pattern is a single base identity that assumes roles into other accounts, so you store one set of keys and reach many accounts.

Recipe

Copy-paste the file layout, then select a profile three ways.

# ~/.aws/config
[default]
region = us-east-1
output = json
 
[profile staging]
region = us-east-1
output = json
 
[profile prod-readonly]
region = us-west-2
output = json

# ~/.aws/credentials
[default]
aws_access_key_id = AKIA_DEFAULT
aws_secret_access_key = secret_default
 
[staging]
aws_access_key_id = AKIA_STAGING
aws_secret_access_key = secret_staging

# Select a profile from the CLI
aws s3 ls --profile staging
 
# Or set it for the whole shell
export AWS_PROFILE=staging
aws sts get-caller-identity

When to reach for this:

• You work across more than one AWS account (dev / staging / prod).
• You need both a read-only and a read-write identity for the same account.
• You want role assumption without pasting temporary keys by hand.
• You share scripts that must run against different accounts unchanged.

Working Example

The same account selection in both SDKs, choosing a profile explicitly in code.

# --- Python (boto3) ---
import boto3
 
# A Session bound to a specific named profile.
session = boto3.Session(profile_name="staging")
 
sts = session.client("sts")
identity = sts.get_caller_identity()
print("staging account:", identity["Account"])
 
# A different profile, same process, no env changes.
prod_session = boto3.Session(profile_name="prod-readonly")
s3 = prod_session.client("s3")
buckets = s3.list_buckets()
print("prod buckets:", [b["Name"] for b in buckets["Buckets"]])

// --- TypeScript (AWS SDK v3) ---
import { fromIni } from "@aws-sdk/credential-providers";
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
 
// A credential provider bound to a specific named profile.
const sts = new STSClient({ credentials: fromIni({ profile: "staging" }) });
const identity = await sts.send(new GetCallerIdentityCommand({}));
console.log("staging account:", identity.Account);
 
// A different profile, same process, no env changes.
const s3 = new S3Client({
  region: "us-west-2",
  credentials: fromIni({ profile: "prod-readonly" }),
});
const buckets = await s3.send(new ListBucketsCommand({}));
console.log("prod buckets:", buckets.Buckets?.map((b) => b.Name));

What this demonstrates:

• Selecting a profile in code with Session(profile_name=...) in boto3 and fromIni({ profile }) in v3.
• Using two different profiles in the same process without touching environment variables.
• boto3 reads region from the profile automatically; v3's fromIni supplies only credentials, so you pass region on the client.
• No access keys appear in the code - both SDKs read the shared files.

Deep Dive

How It Works

• Profiles are INI-style blocks. The credentials file uses a bare header like [staging]; the config file uses [profile staging] (with the profile prefix).
• The one exception is default - it is [default] in both files, never [profile default].
• When you name a profile, the CLI and SDKs merge that profile's entries from both files into one resolved configuration.
• Region and output live in config; long-lived keys live in credentials. SSO and role settings live in config.

Assuming a Role Across Accounts

Store one base identity and let a profile assume a role in another account.

# ~/.aws/config
[profile base]
region = us-east-1
 
[profile prod-admin]
role_arn = arn:aws:iam::222222222222:role/OrgAdmin
source_profile = base
region = us-east-1

• source_profile names the identity whose keys sign the AssumeRole request.
• role_arn is the role to assume in the target account.
• The CLI and both SDKs perform the AssumeRole call automatically and cache the temporary credentials.
• Add mfa_serial = arn:aws:iam::...:mfa/you to require an MFA code on assumption.

Config vs Credentials at a Glance

Gotchas

• Wrong header prefix - Putting [profile staging] in the credentials file (or [staging] in config) makes the profile invisible. Fix: bare [name] in credentials, [profile name] in config; default is always bare.
• v3 fromIni ignores region - fromIni returns only credentials, so a v3 client with no region throws a region error. Fix: pass region on the client, or set AWS_REGION.
• Editing the wrong file - Adding region to credentials has no effect. Fix: region belongs in config.
• Forgetting source_profile - A role_arn profile with no source_profile (and no other base credentials) cannot sign the assume-role call. Fix: add source_profile or credential_source.
• Committing the files - ~/.aws/credentials holds live secrets; a leaked commit is a breach. Fix: never place these files in a repo; keep them in the home directory only.
• Assuming profile names are validated - A typo in --profile stagng yields a "profile not found" error, not a fallback to default. Fix: run aws configure list-profiles to confirm names.

Alternatives

FAQs

aws configure list-profiles

Related

• AWS CLI Setup Basics - install the CLI and create your first profile.
• AWS SSO / IAM Identity Center CLI Login - profiles backed by short-lived SSO credentials.
• Environment Variables vs Config File Precedence - which source wins when several are set.
• The AWS CLI as the SDK's Shared Credential Backbone - why both SDKs read these files.

Stack versions: This page was written for the AWS CLI v2, boto3 1.43.x (Python 3.10+), and the AWS SDK for JavaScript v3 (Node.js 18+).