Home

AWS Credentials File: Configure and Manage ~/.aws/credentials

Learn how to create, use, secure, and troubleshoot the AWS shared credentials file, profiles, temporary credentials, and AWS CLI and SDK authentication.

The AWS shared credentials file stores local values that AWS tools can use to authenticate API requests. Its standard location is ~/.aws/credentials on Linux and macOS, and %UserProfile%\.aws\credentials on Windows.

This file is useful for local development and administration, but long-lived access keys should be avoided when temporary credentials, IAM roles, or IAM Identity Center are available.

What AWS Credentials Do

AWS credentials are values used to authenticate calls to AWS APIs. Authentication answers “Who is making this request?” Authorization then determines whether that identity is allowed to perform the requested action.

Credentials are different from an AWS account ID and a console password:

  • An AWS account ID identifies an AWS account. It is not a secret and cannot authenticate API requests.
  • A console password is used for interactive sign-in to the AWS Management Console.
  • Programmatic credentials authenticate requests made by the AWS CLI, an AWS SDK, or another API client.

The common credential elements are:

  • Access key ID: a public identifier for a programmatic access key.
  • Secret access key: the private value paired with the access key ID. Treat it as a password.
  • Session token: an additional value required for temporary credentials.

Where the Shared Credentials File Lives

Linux and macOS: credentials are normally read from ~/.aws/credentials. The tilde represents the current user's home directory.

Windows: credentials are normally read from %UserProfile%\.aws\credentials.

Configuration file: related settings are normally stored in ~/.aws/config on Linux and macOS, or %UserProfile%\.aws\config on Windows.

Alternate credentials path: set AWS_SHARED_CREDENTIALS_FILE to point to another credentials file.

A new local user may need to create the .aws directory and the credentials file. On Linux or macOS:

mkdir -p ~/.aws && chmod 700 ~/.aws

On Windows, create the .aws directory beneath the user profile directory. The AWS CLI can also create the files when you run aws configure.

For a nonstandard file location:

export AWS_SHARED_CREDENTIALS_FILE=/secure/path/credentials

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

Credentials File Format and Profiles

The shared credentials file uses an INI-style format. A profile is a named collection of credentials. The default profile is used when no profile is selected explicitly.

A minimal default profile looks like this:

[default]
aws_access_key_id = AKIAEXAMPLE
aws_secret_access_key = REPLACE_WITH_SECRET

Never use example values as real credentials. Replace placeholders only in a protected local file or through an approved configuration process.

A named profile can keep development credentials separate:

[development]
aws_access_key_id = AKIAEXAMPLE
aws_secret_access_key = REPLACE_WITH_SECRET

Temporary credentials contain all three values:

[temporary]
aws_access_key_id = ASIAEXAMPLE
aws_secret_access_key = REPLACE_WITH_SECRET
aws_session_token = REPLACE_WITH_SESSION_TOKEN

Use AWS_PROFILE to select a profile for the current shell:

export AWS_PROFILE=development

Or select one for a single AWS CLI command:

aws sts get-caller-identity --profile development

In the credentials file, named profiles use headings such as [development]. This differs from the AWS config file, where a named profile heading normally includes the word profile, such as [profile development].

Credentials File Fields

aws_access_key_id: required for both long-lived and temporary access keys; identifies the key.

aws_secret_access_key: required for both types; signs requests and must remain secret.

aws_session_token: required for temporary credentials; proves that the temporary session is valid and has not expired.

For temporary credentials, omitting the session token usually causes authentication to fail even when the access key ID and secret access key are correct.

Obtaining Credentials Safely

For human users, prefer short-lived credentials from IAM roles, IAM Identity Center, or federation. These options reduce the damage caused by accidental exposure and avoid storing permanent secrets on developer workstations.

Create IAM user access keys only when long-lived programmatic credentials are specifically required and an approved security process allows them. Do not create or use root account access keys for routine work.

A secret access key is shown only when it is created. It cannot be retrieved later. Record it immediately through an approved secure method, or create a replacement if it was lost.

Use least privilege: grant an identity only the permissions required for its task. Prefer separate identities or profiles for development, testing, and production.

Relationship Between credentials and config

The shared credentials file is primarily for authentication values. The shared config file is commonly used for settings such as region, output format, IAM Identity Center configuration, and role-assumption settings.

For example, ~/.aws/config might contain:

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

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

The development profile can therefore combine credentials from ~/.aws/credentials with region and output settings from ~/.aws/config.

A role profile commonly belongs in the config file while its source credentials remain in the credentials file:

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

Here, the CLI first uses the development source profile, then requests temporary credentials for AuditRole through AWS STS AssumeRole.

How AWS Tools Find Credentials

The AWS CLI and AWS SDKs use a credential provider chain: an ordered set of possible credential sources. The exact order can vary by SDK and configuration, but explicitly supplied credentials and standard environment variables generally take precedence over shared-file values.

  • Credentials explicitly supplied in application code or a command configuration may take precedence.
  • Environment variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN can override values in the shared credentials file.
  • The selected shared credentials profile is controlled by AWS_PROFILE or a CLI --profile option.
  • The shared credentials file and shared config file provide local profile data.
  • IAM Identity Center sessions, role credentials, and instance or container roles can provide temporary credentials without a permanent local secret.

Because environment variables can override files, inspect them when a command uses an unexpected account or role. Do not print secret values while diagnosing the provider chain.

Using the AWS CLI

The interactive command aws configure creates or updates the default profile:

aws configure

To configure a named profile:

aws configure --profile development

Verify the identity represented by the default profile:

aws sts get-caller-identity

Verify a named profile:

aws sts get-caller-identity --profile development

The response identifies the AWS account and principal represented by the loaded credentials. Run this check before making changes, especially when working across multiple accounts.

Temporary Credentials and Role Assumption

Temporary security credentials are issued for a limited lifetime by services such as AWS STS. They consist of an access key ID, secret access key, and session token. When the session expires, the values stop authenticating requests.

Temporary credentials may come from IAM Identity Center, federation, an assumed IAM role, or an AWS-managed workload identity such as an instance or container role.

For interactive workforce access, IAM Identity Center is generally preferable to distributing long-lived IAM user keys. A typical workflow is to authenticate with the organization's Identity Center process, select an account and permission set, and let the CLI or SDK obtain renewable temporary credentials.

For local development that needs another role, use a source profile and a role profile in the config file:

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

Select the role profile when running a command:

aws sts get-caller-identity --profile audit-role

The source identity must be permitted to call sts:AssumeRole, and the target role's trust policy must allow that source identity.

Security Practices

  • Treat access key IDs, secret access keys, and session tokens as sensitive. Although an access key ID is not sufficient by itself to authenticate, protect it together with the other values.
  • On Linux and macOS, restrict the credentials file to its owner:
chmod 600 ~/.aws/credentials
  • Do not place credentials files, keys, tokens, or copied command output in source control, tickets, chat, or documentation.
  • Add credential filenames and local secret locations to .gitignore, and enable repository secret scanning.
  • Rotate access keys regularly when long-lived keys are unavoidable. Deactivate and delete unused keys.
  • If a key is exposed, immediately deactivate it, create a replacement through an approved process, update dependent applications, and review activity in AWS auditing tools.
  • Avoid storing secrets on shared machines. Use separate operating-system accounts and protected credential stores where possible.
  • Prefer short-lived credentials and least-privilege IAM policies.

Troubleshooting Credential Loading

Start with identity verification:

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

Separate two categories of failure:

  • Credential discovery or authentication failure: the tool cannot find credentials, the values are invalid, or a temporary session has expired.
  • Authorization failure: the credentials are valid, but the identity is not allowed to perform the requested action.

For deeper diagnostics, use debug output carefully:

aws sts get-caller-identity --debug

Review the output locally. Never publish debug logs because they may reveal usernames, profile names, account information, request details, or accidental secret material.

Common Errors

Unable to locate credentials: no credentials were found, the wrong home directory or operating-system user is active, AWS_SHARED_CREDENTIALS_FILE points to a missing file, or the intended profile was not selected. Check the path, profile, environment variables, and file contents, then verify with STS.

The config profile could not be found: the profile name may be misspelled or its heading may use the wrong syntax. Use [name] in the credentials file and [profile name] in the config file.

ExpiredToken: temporary, role, federation, or Identity Center credentials expired. Renew the session and remove stale temporary environment variables that override the renewed profile.

InvalidClientTokenId: the key may be mistyped, deleted, deactivated, or invalid in context. Temporary credentials may also be missing aws_session_token. Confirm key status and replace invalid values.

SignatureDoesNotMatch: the secret does not match the access key, copied whitespace or an environment override is interfering, or the system clock is inaccurate. Check the credential source and synchronize the clock.

AccessDenied: authentication succeeded, but IAM or an organization, session, resource, or permissions-boundary policy denied the action. Confirm the principal with STS and review the narrowly relevant policies.

Unexpected account or role: AWS_PROFILE, environment credentials, AWS_SHARED_CREDENTIALS_FILE, or a role profile may be active. Inspect those selectors and explicitly choose the intended profile.

Practical Configuration Checklist

  1. Choose temporary credentials, IAM Identity Center, or an IAM role whenever possible.
  2. Create ~/.aws with restricted permissions if it does not exist.
  3. Put only the required authentication values in ~/.aws/credentials.
  4. Put region, output, and role settings in ~/.aws/config.
  5. Select the intended profile with AWS_PROFILE or --profile.
  6. Run aws sts get-caller-identity before using other commands.
  7. Protect the files, scan repositories for secrets, and rotate or deactivate unused keys.

Key Exam Notes

  • ~/.aws/credentials stores shared local credential profiles; ~/.aws/config commonly stores region, output, SSO, and role settings.
  • Named profile headings differ: [name] in credentials versus [profile name] in config.
  • Temporary credentials require an access key ID, secret access key, and session token.
  • Environment variables and explicitly supplied credentials can override shared-file values.
  • aws sts get-caller-identity identifies the effective principal and helps distinguish wrong-identity problems from permission problems.
  • AccessDenied usually means credentials were accepted but the identity lacks permission; Unable to locate credentials indicates a discovery problem.

For this topic's reference path, see AWS credentials.