AWS Shared Credentials File

Learn how to create, locate, use, verify, and secure AWS CLI and SDK profiles in the shared credentials file.

The AWS shared credentials file stores local programmatic credentials in named profiles. AWS CLI commands, SDKs, and other AWS tools can use these profiles to authenticate requests. The standard Unix-like location is ~/.aws/credentials.

What AWS credentials do

Credentials authenticate a request as an AWS principal. A principal can be an IAM user, an IAM role, or a federated identity that has obtained temporary credentials. Authentication answers “Who is making this request?” Authorization then evaluates whether that principal has permission to perform the requested action.

An AWS account contains IAM identities and resources. IAM policies grant or deny permissions to those identities. Credentials do not grant permissions by themselves; they identify the principal whose policies and other policy controls are evaluated.

Long-lived access keys and temporary credentials

An AWS access key ID is the public identifier portion of a programmatic access key.
An AWS secret access key is the confidential signing key paired with the access key ID.
A session token is an additional value required with temporary credentials.

Long-lived access keys are associated with IAM users and do not contain an expiration time. Temporary credentials are issued by AWS STS or an authentication workflow, expire after a limited period, and normally include all three values: access key ID, secret access key, and session token. Prefer temporary credentials whenever a role, IAM Identity Center, federation, or another short-lived workflow is available.

Default location and file format

Operating system	Default credentials path	Default config path	Notes
Linux and other Unix-like systems	`~/.aws/credentials`	`~/.aws/config`	`~` means the current user's home directory.
Windows	`%UserProfile%\.aws\credentials`	`%UserProfile%\.aws\config`	The exact expanded path depends on the Windows user profile directory.

The shared credentials file uses INI-style sections. The section named [default] is used when no profile is selected. A named profile uses a section such as [development] or [production].

[default]
aws_access_key_id = EXAMPLEACCESSKEYID
aws_secret_access_key = EXAMPLESECRETACCESSKEY

[development]
aws_access_key_id = EXAMPLEDEVACCESSKEYID
aws_secret_access_key = EXAMPLEDEVSECRETACCESSKEY

Credential fields

Field	Purpose	When required
`aws_access_key_id`	Identifies the access key.	Required for access-key-based credentials.
`aws_secret_access_key`	Secret used to sign AWS requests.	Required with the access key ID.
`aws_session_token`	Proves that the request uses a valid temporary session.	Required with temporary credentials.

Protect the secret access key as you would a password. AWS does not let you retrieve the secret access key again after its creation. If it is lost, create a replacement access key through IAM and deactivate or delete the old one according to your access-key lifecycle process. A session token is also sensitive and must not be disclosed.

Creating profiles

Configure the default profile

Run the interactive command below and answer its prompts:

aws configure

This normally writes access-key values to the credentials file and region or output settings to the config file.

Configure a named profile

aws configure --profile development

Use named profiles when you work with multiple accounts, environments, or permission sets. Explicit names make it easier to avoid running a production command with development credentials.

Edit the file manually

Manual editing is useful for controlled environments or for adding temporary credentials. Use an exact section header and one key-value pair per line:

[temporary]
aws_access_key_id = EXAMPLETEMPACCESSKEYID
aws_secret_access_key = EXAMPLETEMPSECRETACCESSKEY
aws_session_token = EXAMPLESESSIONTOKEN

Do not put a profile prefix in a named credentials-file section. For example, use [development], not [profile development]. Preserve valid INI syntax, avoid duplicate or misspelled keys, and ensure the file is readable by the intended user.

Create and manage IAM access keys through IAM, never by using root-user access keys. Root-user keys should not be used for routine CLI or application access.

Credentials file versus config file

Aspect	Shared credentials file	Config file
Default path	`~/.aws/credentials`	`~/.aws/config`
Typical contents	Access key ID, secret access key, and session token.	Region, output format, role settings, SSO settings, credential processes, and other CLI or SDK configuration.
Default profile header	`[default]`	`[default]`
Named profile header	`[development]`	`[profile development]`
How values are used	Supplies credentials for a selected profile.	Supplies non-secret settings and, in some workflows, instructions for obtaining credentials.

A selected profile can combine values from both files. For example, credentials may come from [development] in the credentials file while the region comes from [profile development] in the config file. The files are separate, but AWS tools use the matching profile name to assemble the effective configuration.

Selecting and using profiles

With no selection option or profile environment variable, the AWS CLI uses the default profile:

aws s3 ls

Select a profile for one command with --profile:

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

Select a profile for the current shell session with AWS_PROFILE:

export AWS_PROFILE=development
aws s3 ls

On Windows PowerShell, the equivalent is:

$env:AWS_PROFILE = "development"

Method	Example	Scope	Typical use
Default selection	`aws s3 ls`	Command	Routine use of `default`.
Command option	`--profile development`	One command	High-confidence selection for sensitive operations.
Environment variable	`export AWS_PROFILE=development`	Current shell and child processes	Working in one environment for a session.

SDKs and AWS tools commonly use a default credential provider chain. This is an ordered set of credential sources that can include explicit application settings, environment variables, shared files, role or credential-process sources, and instance or container metadata. Exact details vary by SDK and version, so verify the effective identity instead of assuming the file is being used.

Credential precedence and provider chain

Credential source	Typical environment	Can override file-based credentials	Security considerations
Explicit application or command settings	Code, command options, or tool-specific configuration.	Usually yes.	Do not embed secrets in source code or scripts.
Environment variables	Developer shells, CI jobs, and process environments.	Yes, in many tools.	They can silently select a different identity and may leak through logs or diagnostics.
Shared credentials and config files	Local development.	Used when higher-priority sources are absent.	Restrict permissions and exclude files from source control.
Assume-role, SSO, or credential-process sources	Federated access and cross-account workflows.	Can supply or replace file-based keys.	Sessions expire and must be refreshed.
Instance, container, or task metadata	EC2, ECS, and other managed workloads.	Often used when local sources are absent.	Protect workload metadata endpoints and use least privilege.

Environment variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN may override values that you expect to come from the credentials file. The AWS_PROFILE variable can also change which profile is selected.

Temporary credentials and IAM roles

An IAM role is an identity with permissions that can be assumed. AWS STS issues temporary credentials for an assumed role. A role profile usually identifies a role_arn and a source_profile; the source profile authenticates the caller that is allowed to assume the role.

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

Here, production-role does not store a second long-lived access key. The tool uses development as the source, requests the specified role, and caches or uses temporary role credentials for a role session. Those credentials expire. Refresh the source login or role session rather than manually reusing an expired token.

IAM Identity Center and other federated login methods are preferred where available because they can provide short-lived credentials without distributing permanent IAM user keys. Workloads should generally use attached roles, workload identity, or another managed identity mechanism instead of files containing long-lived secrets.

Changing the shared-file location

Set AWS_SHARED_CREDENTIALS_FILE when a tool must use a controlled alternate credentials file:

export AWS_SHARED_CREDENTIALS_FILE=/secure/path/credentials

Similarly, AWS_CONFIG_FILE changes the location of the config file:

export AWS_CONFIG_FILE=/secure/path/config

These variables affect the processes that inherit them. Check their values when troubleshooting isolated environments, CI jobs, wrappers, and shell startup files.

Verification commands

List profiles visible to the AWS CLI:

aws configure list-profiles

Inspect the sources and values currently selected for a profile. Sensitive values may be masked:

aws configure list --profile development

Confirm the actual AWS account and principal before a sensitive operation:

aws sts get-caller-identity --profile development

The response includes the AWS account, an ARN, and an identifier. This verifies the effective identity, including cases where environment variables, a role profile, SSO, or metadata credentials took precedence over the file you inspected.

Security and credential hygiene

Never commit ~/.aws/credentials, access keys, session tokens, or generated secret files to source control.
Add credential files and local secret files to appropriate ignore rules, but do not treat ignore rules as a substitute for removing an already exposed secret.
Set restrictive local permissions so other users cannot read the file. On Unix-like systems, a typical hardening command is chmod 600 ~/.aws/credentials; confirm that ownership is also correct.
Use least-privilege IAM policies and separate profiles or roles for different environments.
Rotate access keys, deactivate unused keys, and remove them when no longer needed.
Do not place secrets in scripts, command arguments, shell history, container images, shared configuration, or build logs.
If a credential is exposed, deactivate or revoke it immediately, investigate CloudTrail and other relevant telemetry for misuse, and replace it through the approved process.

Troubleshooting

Symptom or error	Likely cause	Diagnostic step	Resolution
Unable to locate credentials	No usable credentials, wrong file location, inaccessible permissions, or missing profile selection.	Run `aws configure list`, `aws configure list-profiles`, and inspect the effective home and file-path variables.	Configure the intended profile, set `AWS_PROFILE` or `--profile`, and correct path, ownership, or permissions.
Wrong AWS account or identity	Unexpected `AWS_PROFILE`, environment credentials, default profile, or role profile.	Run `aws sts get-caller-identity`, inspect `aws configure list`, and review active `AWS_*` variables.	Explicitly select the intended profile and unset unintended environment variables.
`ExpiredToken`	Temporary STS credentials or an SSO/federated session expired.	Check whether the profile uses session credentials, a role, or a federated login.	Sign in again or rerun the appropriate credential process. Do not reuse expired tokens.
`AccessDenied`	The authenticated principal lacks permission, or an explicit deny, boundary, resource policy, or service control policy applies.	Verify the identity and review the action, resource, and applicable policy layers.	Grant only the minimum required permission through the correct policy layer; changing credentials without identifying the principal does not fix authorization.
Profile not found or parsing failure	Misspelled profile, malformed INI syntax, or incorrect named-profile header in the config file.	List profiles and inspect section headers and key-value formatting.	Use `[name]` in credentials and `[profile name]` in config for named profiles.

Use debug output carefully

CLI debug output can show which providers and files are being considered:

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

Debug output can contain paths, request details, or other sensitive context. Review it before sharing, redact secrets, and avoid collecting it in public logs.

Practical workflow

Choose a least-privilege IAM user key only when a temporary or federated method is unavailable.
Run aws configure or aws configure --profile development, or edit the files with valid syntax.
Set the region and other non-secret settings in the matching config profile.
Check available profiles with aws configure list-profiles.
Verify the account and principal with aws sts get-caller-identity.
Use --profile for sensitive one-off commands or set AWS_PROFILE for a controlled shell session.
Prefer role assumption, IAM Identity Center, or workload identity for ongoing access, and refresh temporary sessions when they expire.

Exam note: The credentials file commonly contains access-key material, while the config file commonly contains regions and role or CLI settings. For a named profile, the credentials file uses [name], whereas the config file uses [profile name]. Always verify the effective principal with STS because provider precedence can select credentials other than the ones you expect.