AWS Shared Credentials File: Profiles, Format, and Secure Usage

Learn how the AWS shared credentials file works, where it is stored, how to manage profiles, troubleshoot authentication, and use temporary credentials securely.

What the AWS shared credentials file does

The AWS shared credentials file is a local, INI-formatted file containing named AWS credential profiles. A profile is a named set of authentication and related settings that an AWS tool can use.

The AWS Command Line Interface (AWS CLI) and many AWS SDKs can read this file through the shared configuration system. It is useful when you work locally with several AWS accounts, roles, or environments.

This file is intended for local user-level credentials. It is not a suitable place for secrets that are committed to an application repository, copied into a container image, or shared with other users.

Credentials file versus configuration file

File	Typical location	Primary purpose	Common settings	Secret material considerations
Shared credentials file	`~/.aws/credentials`	Stores credential profiles	`aws_access_key_id`, `aws_secret_access_key`, `aws_session_token`	Usually contains sensitive secret material; protect it carefully
Shared configuration file	`~/.aws/config`	Stores general CLI and SDK settings	Region, output format, role settings, and IAM Identity Center settings	Often contains nonsecret settings, but role and SSO details still deserve protection

Matching profile names from the two files are combined. For example, credentials in [development] can be combined with region settings in [profile development] in the configuration file.

On this page, AWS credentials means the local profile data used by compatible AWS tools.

Default file locations

On Linux and macOS, the standard shared credentials file is:

~/.aws/credentials

The tilde character, ~, represents the current user's home directory. For example, for a user whose home directory is /home/alex, the path expands to /home/alex/.aws/credentials.

On Windows, the equivalent per-user path is normally:

%UserProfile%\.aws\credentials

The exact home directory depends on the user running the AWS CLI or SDK application. A service, scheduled task, container, or remote session may use a different user and therefore a different home directory.

Using a nondefault credentials file

Compatible tools can use the AWS_SHARED_CREDENTIALS_FILE environment variable to select another credentials file. On Linux or macOS:

export AWS_SHARED_CREDENTIALS_FILE="$HOME/.aws/project-credentials"

Use a separate file only when its ownership, permissions, backup policy, and exclusion from version control are understood. The related AWS_CONFIG_FILE variable changes the location of the shared AWS configuration file.

Credentials file format

The file uses INI-style sections. Each section is a profile, and each setting is written as a key-value pair.

[default]
aws_access_key_id = EXAMPLEACCESSKEY
aws_secret_access_key = example-secret-value

[development]
aws_access_key_id = EXAMPLEDEVKEY
aws_secret_access_key = example-development-secret

The default and named profiles

The [default] section is used when no profile is selected explicitly. A named section, such as [development] or [production], is used when that profile is selected.

Credentials-file sections use the profile name directly. Thus, the credentials file uses [development], while the configuration file commonly uses [profile development]. This naming difference is important.

Credential keys

aws_access_key_id: the public identifier portion of an AWS access key pair.
aws_secret_access_key: the secret portion of an AWS access key pair. Treat it as a password.
aws_session_token: an additional token required with temporary credentials.

A temporary profile normally contains all three credential keys:

[temporary]
aws_access_key_id = EXAMPLETEMPKEY
aws_secret_access_key = example-temporary-secret
aws_session_token = example-session-token

Do not replace example values with real secrets in documentation, tickets, chat messages, or source code.

Creating and editing profiles

Use the AWS CLI configuration command

The simplest method for a new local profile is interactive configuration:

aws configure

This normally asks for an access key ID, secret access key, default region, and output format. Credential values are written to the credentials file, while region and output preferences are normally written to the configuration file.

To create or update a named profile, specify its name:

aws configure --profile development

Use separate names such as development, testing, and production when those environments use different accounts or identities. Selecting a profile explicitly reduces the chance of accidentally running a production command with development credentials, or the reverse.

Direct editing

You can edit the INI file directly, but do so only when you understand file permissions, secret handling, and the syntax. Avoid leaving secrets in shell history or temporary editor files. Use the CLI or a supported short-lived authentication workflow when possible.

Profile selection

Method	Scope	Example	When to use it
`--profile`	One command	`aws s3 ls --profile development`	Safest for isolated commands and scripts that intentionally name an account
`AWS_PROFILE`	Current process or shell session	`export AWS_PROFILE=development`	When several commands in a session should use one profile
Default profile	Process without an explicit selection	`[default]`	Convenient for a primary local identity, but easier to use accidentally

For a single command, prefer --profile when clarity matters. For a Linux or macOS shell session, use:

export AWS_PROFILE=development

On Windows, set the equivalent environment variable using the shell's environment-variable syntax.

How the credentials and configuration files work together

The credentials file generally holds secret key material. The configuration file commonly holds a region, output format, role-assumption settings, and IAM Identity Center settings.

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

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

In this example, the credentials file needs a [development] profile. The configuration file's [profile deployment-role] section uses that source profile to obtain credentials for the deployment role.

Region resolution

Authentication and region selection are separate concerns. A profile can contain valid credentials but still fail for a regional service operation if no region is available.

A region may come from the selected profile in the configuration file, environment variables such as AWS_REGION or AWS_DEFAULT_REGION, or an explicit command option such as --region. You can set a profile's region with:

aws configure set region us-east-1 --profile development

Credential resolution and provider chains

A credential provider chain is the ordered set of places and mechanisms a tool examines to obtain credentials. Conceptually, a process may receive credentials from explicitly supplied values, environment variables, selected profiles, or a runtime identity provider.

Environment variables can override credentials read from a profile file. Common variables include AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN. AWS_PROFILE selects a named profile when no more specific credential source takes precedence.

Other providers include assumed-role credentials, web identity credentials, ECS task credentials, EC2 instance roles, IAM Identity Center sessions, and other runtime mechanisms. These alternatives are particularly important for deployed applications, which should generally not depend on a developer's local credentials file.

Long-term and temporary credentials

Credential method	Lifetime	Where settings are commonly stored	Recommended use case	Key security concern
IAM user access keys	Long-lived until rotated, deactivated, or deleted	Local credentials file or a secure secret manager	Limited compatibility cases and controlled local development	Exposure can provide continuing access until action is taken
STS temporary credentials	Time-limited	Short-lived profile data, cache, or environment supplied by a tool	Assumed roles, federation, and temporary sessions	They require a session token and expire
IAM Identity Center	Session-based	SSO configuration and local cached tokens	Human access across accounts and permission sets	Refresh the sign-in session and protect the local user account
Workload identity	Managed by the runtime	ECS task role, EC2 instance role, or web identity configuration	Applications running on AWS or with federation support	Overly broad role permissions affect the workload

IAM user access keys are long-term credentials. Temporary credentials are commonly issued by AWS Security Token Service (AWS STS) or a federation flow and include an access key ID, secret access key, and session token. They expire by design.

When temporary credentials expire, do not keep reusing the old values. Refresh the authentication flow and obtain a new session. Prefer IAM Identity Center, assume-role workflows, or workload identity over long-lived static keys when those methods fit the use case.

Role-based profiles

An IAM role is an AWS identity with permissions that can be assumed to receive temporary credentials. A role profile commonly references a source profile, which supplies the initial identity.

Role settings normally belong in the configuration file:

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

The development profile provides the starting credentials. The AWS CLI or SDK uses them to call AWS STS, assumes the role identified by role_arn, receives temporary credentials, and performs commands as the assumed role.

Some roles require multi-factor authentication (MFA). In that case, configure the role-assumption workflow with the required MFA device information and provide the requested code when the tool prompts for it. The source identity must also be authorized to assume the role.

IAM Identity Center and modern local authentication

IAM Identity Center provides browser-based sign-in and temporary local CLI authentication. An Identity Center profile normally stores SSO configuration and uses cached tokens rather than permanent access keys in the credentials file.

A conceptual workflow is:

aws sso login --profile company-sso
aws sts get-caller-identity --profile company-sso

After login, commands can use the profile:

aws s3 ls --profile company-sso

An SSO profile may not create static aws_access_key_id and aws_secret_access_key entries in ~/.aws/credentials. That is expected: the tool obtains temporary credentials from the authenticated SSO session and its cache.

Security practices

Treat access key IDs, secret access keys, and session tokens as secrets. Although an access key ID is an identifier, handle the complete credential set as sensitive.
Use restrictive file permissions and ensure the file is owned by the intended local user. On Linux and macOS, a common permission is:

chmod 600 ~/.aws/credentials

Do not store credentials in source repositories, container images, shared home directories, issue tickets, chat messages, or documentation examples containing real values.
Add local credential files and project-specific credential files to .gitignore, and enable secret-scanning controls in repositories and CI systems.
If a key is exposed, immediately deactivate or delete it, investigate use, and rotate any related credentials. Do not wait for the key to expire if it is long-lived.
Use least privilege: grant only the permissions needed for the task.
Do not create or use root account access keys for routine work.
Prefer federated authentication, IAM Identity Center, assumed roles, and temporary workload credentials over long-lived static keys.
Keep human credentials separate from automated workload credentials. A deployed application should use its runtime identity or an approved secret-management mechanism, not a developer's home directory.

Safe inspection and verification

Use the AWS CLI to inspect configuration sources without printing secret values:

aws configure list
aws configure list --profile development

List profiles known to the AWS CLI:

aws configure list-profiles

Confirm the active AWS identity and account with AWS STS:

aws sts get-caller-identity --profile development

Using --profile verifies a specific profile without changing the default profile or the rest of the shell session. The result identifies the account and principal used for the request.

Common maintenance tasks

Add or change a profile

Run the named configuration command to add a profile or update its access key:

aws configure --profile testing

If you replace an IAM user access key, update the profile and then verify the resulting identity. For temporary credentials, refresh the issuing workflow instead of manually editing expired values.

Remove an obsolete profile

Remove the complete matching section from the credentials file and remove its matching section from the configuration file if one exists. Before deleting it, confirm that no scripts, services, or role profiles use that name.

Switch profiles

Use a profile for one command:

aws s3 ls --profile development

Or select one for the current Linux or macOS shell:

export AWS_PROFILE=development

Check the effective source and identity after switching. Clear an old shell's overriding credential variables if they are causing an unexpected result.

Redirect credentials for an isolated workflow

export AWS_SHARED_CREDENTIALS_FILE="$HOME/.aws/project-credentials"
aws configure list-profiles

Keep the alternate file outside version control and protect it with the same ownership and permission standards as the default file.

Troubleshooting authentication

Symptom or error category	Likely cause	How to verify	Corrective action
Cannot locate credentials	No usable profile, wrong selected profile, missing alternate file, or a different home directory	Run `aws configure list` and `aws configure list-profiles`; check `AWS_PROFILE`, `AWS_SHARED_CREDENTIALS_FILE`, path, and permissions	Create or select the correct profile, fix environment variables, and make the file readable by the active user
Unexpected account or IAM identity	Credential environment variables, another `AWS_PROFILE`, a role profile, or a container or instance role	Run `aws configure list` and `aws sts get-caller-identity`; inspect credential variables	Remove overrides, select the intended profile, and verify role configuration
Expired-token error	Temporary credentials, an SSO session, or cached role credentials expired	Check for `aws_session_token`, identify the authentication method, and run identity verification	Sign in again or obtain a new temporary session
No region configured	No region in the selected config profile or environment	Run `aws configure list --profile PROFILE` and inspect `~/.aws/config`	Set a region in config, use `aws configure set region REGION --profile PROFILE`, or pass `--region`
Access denied	Missing permission, explicit deny, permission boundary, service control policy, resource policy, session policy, or wrong identity	Verify identity, action, resource, and target account; review applicable policies	Use the correct authorized role or grant the minimum required permission
Works in one application but not another	SDK shared-config behavior, different process environment, different home directory, or SDK-version differences	Review the application's credential-loading settings, process environment, effective user, and SDK version	Enable shared configuration where required, set intended paths and profile variables, or use the SDK's documented provider configuration

Key takeaways

The shared credentials file is a local INI file containing named credential profiles.
Credentials usually go in ~/.aws/credentials; general settings usually go in ~/.aws/config.
Use --profile or AWS_PROFILE to choose an identity deliberately.
Temporary credentials require aws_session_token and must be refreshed after expiration.
Role profiles use source_profile and role_arn in the configuration file.
IAM Identity Center commonly authenticates through cached SSO sessions rather than static entries in the credentials file.
Verify the effective source with aws configure list and the actual identity with aws sts get-caller-identity.
Protect credentials, use least privilege, and prefer temporary or federated authentication.