.Aws

AWS Credentials File (.aws/credentials)

Learn how to create, format, secure, select, troubleshoot, and verify AWS shared credentials-file profiles for the AWS CLI and SDKs.

The AWS shared credentials file is a local INI-format file that stores AWS credential values under named profiles. The AWS Command Line Interface (AWS CLI) and many AWS SDKs can read it when authenticating requests to AWS services.

Credentials answer who is making the request. They are different from account settings and region configuration, which answer questions such as where should the request go and how should output be formatted.

What AWS credentials do

AWS credentials authenticate a user, role, or workload to AWS. An authenticated request is then evaluated by IAM, AWS Identity and Access Management, to determine whether that principal is authorized to perform the requested operation.

A long-term access key normally has two parts:

• Access key ID: the public identifier portion of the key.
• Secret access key: the confidential portion used to sign requests. Treat it like a password; it is generally displayed only when the key is created.

Temporary credentials have a third part: a session token. Temporary credentials expire and are commonly issued by AWS STS, the AWS Security Token Service.

The shared credentials file is only one source in the AWS credential provider chain. This chain is the ordered set of locations and mechanisms that an AWS tool checks for credentials. Other sources can include application settings, environment variables, shared configuration profiles, IAM Identity Center sessions, process providers, web identity tokens, container credentials, and EC2 instance profiles.

Default location and neighboring config file

The credentials file normally contains access-key values. The neighboring config file commonly contains regions, output formats, role settings, IAM Identity Center settings, and other non-secret profile configuration.

For example, a profile can keep credential material in credentials and preferences in config:

[development]
aws_access_key_id = AKIAEXAMPLE
aws_secret_access_key = exampleSecretKey

[profile development]
region = us-west-2
output = json

Use AWS_SHARED_CREDENTIALS_FILE when tools should read a different credentials file:

export AWS_SHARED_CREDENTIALS_FILE="$HOME/secure/aws-credentials"

On Windows, set the equivalent environment variable using the operating system's environment-variable tools or the shell syntax appropriate to your shell.

Credentials file format

The file uses INI-style sections. Each section is a profile, and each setting uses a name followed by a value. In the credentials file, the default profile is written as [default]; named profiles use their names directly in brackets.

Default profile

[default]
aws_access_key_id = AKIAEXAMPLE
aws_secret_access_key = exampleSecretKey

The default profile is selected when no other profile is explicitly chosen and no higher-priority credential source supplies credentials.

Named profiles

[development]
aws_access_key_id = AKIADEVEXAMPLE
aws_secret_access_key = developmentExampleSecret

[production]
aws_access_key_id = AKIAPRODEXAMPLE
aws_secret_access_key = productionExampleSecret

Named profiles are useful for separate accounts, environments, IAM users, or role-based workflows.

Temporary credentials

[temporary]
aws_access_key_id = ASIAEXAMPLE
aws_secret_access_key = temporaryExampleSecret
aws_session_token = exampleSessionToken

Whitespace around the equals sign is normally harmless. Keep section names and field names spelled correctly. Do not put secrets in comments: comments can be committed, copied, logged, or exposed by tools just like other file content.

Profile names in credentials and config

Profile section syntax differs between the two files:

• In ~/.aws/credentials, use [development].
• In ~/.aws/config, use [profile development] for a named profile.
• In ~/.aws/config, the default section remains [default].

Using [profile development] in the credentials file, or [development] in the config file, can cause settings to be ignored or a profile to appear missing.

Selecting a profile

For a temporary selection, prefer the command option:

aws sts get-caller-identity --profile development

For a shell-wide selection:

export AWS_PROFILE=development

Creating and managing profiles

The interactive command writes or updates a profile and commonly asks for an access key ID, secret access key, default region, and output format:

aws configure

To create or update a named profile:

aws configure --profile development

Direct editing is useful when importing temporary credentials, reviewing several profiles, or separating credentials from configuration. However, manual edits can introduce misspelled fields, wrong section syntax, copied whitespace, or accidental secret exposure. Restrict file access and avoid leaving secrets in editor backups, shell history, screenshots, or clipboard managers.

Inspect available profiles and resolved values with:

aws configure list-profiles
aws configure list --profile development

aws configure list-profiles lists locally recognized profile names. aws configure list shows resolved configuration values and their sources, helping identify whether a value came from a file, environment variable, or another provider.

Credential rotation

Credential rotation means replacing an old access key with a new one before or after the old key is disabled. Update the intended profile with the new access key ID and secret access key, test it, and then remove or disable the old key through the approved IAM process. Do not leave disabled or obsolete keys in the file.

If a key may have been exposed, treat it as compromised: report it, disable or delete it according to your organization's process, inspect activity, and replace it. Do not try to make an exposed key safe by merely renaming its profile.

IAM access keys and security practices

IAM users, IAM roles, and workloads can receive permissions. Follow least privilege: grant only the permissions needed for the task, and use separate identities for separate purposes.

• A secret access key must be protected like a password.
• Do not use root-user access keys for everyday development. Root access keys should generally not exist.
• Prefer IAM Identity Center, role assumption, EC2 instance profiles, ECS task roles, or other temporary credential methods over long-term IAM user keys when available.
• Use file permissions that prevent other local users from reading the credentials file.
• Store credentials on encrypted devices and protect backups.
• Exclude .aws directories and credential files from source-control repositories.
• Use secret scanning in repositories and CI systems.

On macOS and Linux, inspect and restrict permissions with commands such as:

ls -l ~/.aws/credentials
chmod 600 ~/.aws/credentials

Permission commands and ownership rules differ on Windows, so use the platform's file-security controls there.

Temporary credentials and role assumption

An IAM role is an AWS identity with permissions that can be assumed. AWS STS issues temporary credentials for an assumed role. The complete set contains an access key ID, secret access key, and session token, along with an expiration time.

When the expiration time passes, requests fail even if the three values are still present in the file. Renew the sign-in or role session and replace the temporary values rather than treating them as permanent keys.

A role-based profile is commonly configured in ~/.aws/config. It can use a source profile, a credential source such as an instance role, or IAM Identity Center settings:

[profile audit]
role_arn = arn:aws:iam::123456789012:role/AuditRole
source_profile = development
region = us-east-1

This approach assumes a role from existing credentials instead of duplicating long-term keys for every role. Other supported configurations can use credential_source or IAM Identity Center login settings. Consult the AWS CLI or SDK documentation for the exact options used by your provider.

Credential resolution and precedence

AWS CLI and SDKs search multiple credential sources. Common sources include:

A commonly encountered order gives explicit application settings and environment variables priority over profile files, but exact precedence varies by SDK, version, and configuration. Consult the relevant SDK documentation and use diagnostic commands rather than assuming the file is active.

An unexpected AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, or AWS_PROFILE can make a tool use different credentials from the ones stored in credentials.

Verifying the active identity

Use AWS STS to identify the principal that the CLI resolved:

aws sts get-caller-identity
aws sts get-caller-identity --profile development

Use the configuration diagnostic command to see where values came from:

aws configure list --profile development

You can then run an innocuous service command, subject to your permissions, such as:

aws s3 ls --profile development

Successful authentication does not imply authorization for every AWS operation. get-caller-identity can succeed while another command returns AccessDenied because IAM permissions, resource policies, permission boundaries, service control policies, session policies, or explicit denies restrict that operation.

Troubleshooting

Unable to locate credentials

• Run aws configure list and inspect the reported sources.
• Run aws configure list-profiles to confirm the profile name.
• Check AWS_SHARED_CREDENTIALS_FILE, AWS_PROFILE, the current user, and the home directory.
• Create or correct the profile with aws configure --profile PROFILE.

The CLI uses the wrong account or role

• Run aws sts get-caller-identity.
• Run aws configure list to find the active credential source.
• Inspect and, where appropriate, unset unintended AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, or AWS_PROFILE values.
• Explicitly use the intended profile with --profile.

The security token included in the request is invalid

• Check field names, section syntax, and copied whitespace without displaying secrets.
• For temporary credentials, confirm that all three fields are present, including aws_session_token.
• Replace deleted, disabled, mistyped, or otherwise invalid credentials through the approved identity-management process.

ExpiredToken or expired session errors

• Temporary STS, role, IAM Identity Center, and federated credentials expire.
• Renew the login or obtain a fresh role session.
• Verify the new principal with aws sts get-caller-identity.

AccessDenied after authentication succeeds

• Confirm the principal with aws sts get-caller-identity.
• Confirm the target account, region, resource, and operation.
• Review effective permissions and explicit denies; do not switch to root credentials as a workaround.

Profile not found or settings ignored

• Check spelling and capitalization of the profile name.
• Use [name] in the credentials file.
• Use [profile name] in the config file, except for [default].
• Run aws configure list-profiles and aws configure list --profile NAME.

Quick reference

• Default credentials file: ~/.aws/credentials on macOS and Linux.
• Windows credentials file: %UserProfile%\.aws\credentials.
• Override the path with AWS_SHARED_CREDENTIALS_FILE.
• Use [default] for the default credentials profile and [name] for named credentials profiles.
• Temporary credentials require access key ID, secret access key, and session token.
• Use --profile or AWS_PROFILE to select a profile.
• Use aws sts get-caller-identity to verify the principal actually in use.

For related details, see the AWS CLI config file, ECS task credentials, and EC2 instance-profile security credentials.