/aws-sdk-python-usage

Credentials Reference

Default Credential Chain

boto3 resolves credentials in this order:

1. Explicit aws_access_key_id/aws_secret_access_key passed to Session() or client()
2. AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN env vars
3. Assume role (role_arn + source_profile / credential_source in the active profile)
4. Web identity token (EKS IRSA via AWS_WEB_IDENTITY_TOKEN_FILE / AWS_ROLE_ARN, or web_identity_token_file in profile)
5. SSO credentials (IAM Identity Center profile; token from aws sso login)
6. ~/.aws/credentials file (default or named profile)
7. Login session (login_session in profile; requires botocore[crt])
8. Credential process (credential_process in profile)
9. ~/.aws/config file (static keys in profile)
10. Legacy boto config (BOTO_CONFIG, ~/.boto, /etc/boto.cfg)
11. Container credentials — ECS task role / EKS Pod Identity (AWS_CONTAINER_CREDENTIALS_RELATIVE_URI or AWS_CONTAINER_CREDENTIALS_FULL_URI)
12. EC2 instance metadata (IMDS)

In most cases, let the default chain handle credential resolution rather than hardcoding credentials.

Sessions

import boto3

# Default session -- shared across boto3.client()/boto3.resource() calls
client = boto3.client("s3")

# Explicit session -- isolated credentials and config
session = boto3.Session(
    profile_name="dev-account",
    region_name="us-west-2",
)
client = session.client("s3")

# Multiple sessions for cross-account access
dev = boto3.Session(profile_name="dev")
prod = boto3.Session(profile_name="prod")
dev_s3 = dev.client("s3")
prod_s3 = prod.client("s3")

Use explicit sessions when you need multiple credential sets or profiles in the same process.

Named Profiles

# Use a profile from ~/.aws/credentials or ~/.aws/config
session = boto3.Session(profile_name="my-profile")
client = session.client("s3")

# Or set via environment variable
# AWS_PROFILE=my-profile

Assume Role (STS)

import boto3

# Assume a role and create a client with the temporary credentials
sts = boto3.client("sts")
response = sts.assume_role(
    RoleArn="arn:aws:iam::123456789012:role/MyRole",
    RoleSessionName="my-session",
    DurationSeconds=3600,
)
creds = response["Credentials"]

client = boto3.client(
    "s3",
    aws_access_key_id=creds["AccessKeyId"],
    aws_secret_access_key=creds["SecretAccessKey"],
    aws_session_token=creds["SessionToken"],
)

For automatic credential refresh when the assumed role expires, use a profile with role_arn in ~/.aws/config:

[profile cross-account]
role_arn = arn:aws:iam::123456789012:role/MyRole
source_profile = default

session = boto3.Session(profile_name="cross-account")
client = session.client("s3")  # credentials auto-refresh

Chained Role Assumption

# ~/.aws/config
[profile role-a]
role_arn = arn:aws:iam::111111111111:role/RoleA
source_profile = default

[profile role-b]
role_arn = arn:aws:iam::222222222222:role/RoleB
source_profile = role-a

Environment Variables

STS Get Caller Identity

Useful for verifying which credentials are in use:

sts = boto3.client("sts")
identity = sts.get_caller_identity()
print(identity["Account"], identity["Arn"])