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

Learn how to create, format, select, verify, and secure AWS CLI and SDK profiles in ~/.aws/credentials, including temporary credentials and troubleshooting.

The AWS shared credentials file is a local INI-formatted file that stores named AWS credential profiles. AWS CLI commands and many AWS SDKs can read these profiles through the standard credential provider chain.

On Unix-like systems, the conventional location is ~/.aws/credentials. On Windows, the corresponding location is typically %USERPROFILE%\.aws\credentials. The exact file can be changed with the AWS_SHARED_CREDENTIALS_FILE environment variable.

This article explains how to create profiles, distinguish the credentials file from the AWS config file, select an identity safely, and diagnose common authentication problems.

What the shared credentials file is for

A profile is a named set of AWS authentication details. A profile can represent a developer identity, an account, an environment, or credentials obtained for a role. Several profiles can coexist in one credentials file.

The credentials file normally contains authentication values:

aws_access_key_id: the identifier portion of a programmatic AWS credential.
aws_secret_access_key: the secret portion paired with the access key ID. Treat it like a password.
aws_session_token: an additional value required by temporary credentials.

General settings such as a default region and output format are commonly stored in ~/.aws/config instead. Keeping authentication values separate from general CLI settings makes the purpose of each file clearer.

Common consumers include the AWS CLI and AWS SDKs that support the standard credential provider chain. An SDK application can request a named profile, use the default profile, or rely on another provider such as environment variables or an instance role.

Credential file structure

The file uses INI-style sections. A section name in square brackets identifies a profile, and each setting uses a key-value pair.

The default profile

The default profile is named default. Tools select it when no explicit profile is requested and no higher-priority credential source supplies credentials.

[default]
aws_access_key_id = EXAMPLEACCESSKEYID
aws_secret_access_key = EXAMPLESECRETACCESSKEY

Named profiles

Any other section name creates a named profile. The following file contains two profiles in one file:

[default]
aws_access_key_id = EXAMPLEDEFAULTKEY
aws_secret_access_key = EXAMPLEDEFAULTSECRET

[development]
aws_access_key_id = EXAMPLEDEVKEY
aws_secret_access_key = EXAMPLEDEVSECRET

For temporary credentials, all three credential fields are needed:

[development]
aws_access_key_id = EXAMPLETEMPACCESSKEY
aws_secret_access_key = EXAMPLETEMPSECRETKEY
aws_session_token = EXAMPLESESSIONTOKEN

The values above are placeholders. Never replace them with real secrets in documentation, source control, tickets, logs, screenshots, or chat.

Shared credentials file fields

Field	Required or Optional	Used With	Purpose	Security Notes
`aws_access_key_id`	Required	Long-lived or temporary credentials	Identifies the access key	Do not disclose; an identifier can help attackers target a credential
`aws_secret_access_key`	Required	Long-lived or temporary credentials	Authenticates requests with the access key ID	Protect like a password and rotate if exposed
`aws_session_token`	Required for temporary credentials; otherwise omitted	Temporary credentials	Proves that the short-lived session is valid	Protect it and refresh it when it expires

Creating and managing profiles

Use AWS CLI configuration commands

The simplest way to create or update the default profile interactively is:

aws configure

To configure a named profile, provide the profile name:

aws configure --profile development

The CLI prompts for an access key ID, secret access key, default region, and output format. Credential values are written to the shared credentials file, while region and output settings are commonly written to the config file.

Direct editing

You can edit ~/.aws/credentials with a text editor, especially when provisioning temporary credentials or reviewing multiple profiles. Preserve the INI section syntax, use the exact field names, and avoid adding accidental spaces or copied control characters to secret values.

On Unix-like systems, restrict access after creating or editing the file:

chmod 600 ~/.aws/credentials

Also check the permissions of the parent directory and ensure that backups, editor swap files, and copied versions do not expose the credentials.

Selecting a profile

Use --profile for one command:

aws s3 ls --profile development

Use AWS_PROFILE to select a profile for the current shell session:

export AWS_PROFILE=development

An explicit command option is useful for sensitive operations because the intended profile is visible on the command line. An environment selection is convenient for a sequence of commands, but remember that it remains active in that shell.

Using a profile from an SDK application

An SDK application can usually select a profile through the SDK's profile-aware session or client configuration. The exact code differs by language and SDK version. A typical application chooses a profile name such as development, then lets the SDK read matching credentials from the shared credentials file and settings from the config file.

For deployed applications, prefer the runtime's role or federated identity provider rather than copying a local credentials file onto a server.

Using a custom credentials-file location

For isolated development or a controlled CI workflow, point AWS tooling at another file:

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

The custom path applies to processes launched with that environment variable. Confirm that the process user can read the file and that the file contains the requested profile.

Long-lived and temporary credentials

Long-lived IAM access keys

IAM access keys consist of an access key ID and a secret access key. They remain usable until they are rotated, disabled, or deleted, subject to the permissions attached to their identity. Their long lifetime increases the impact of accidental disclosure.

Use least-privilege permissions, rotate keys according to your organization's policy, and disable or delete obsolete keys. Prefer role-based or temporary authentication whenever feasible.

Temporary credentials

Temporary credentials are time-limited credentials commonly issued by AWS STS or an identity-based sign-in system. They require:

An access key ID.
A secret access key.
A session token.

When the expiration time is reached, AWS rejects requests made with the session. Refresh or reauthenticate to obtain a new set of values and update the profile or credential provider that supplies them. A profile containing only the access key ID and secret access key is incomplete when those credentials require a session token.

IAM Identity Center, federated sign-in, assumed roles, EC2 instance roles, and container task roles can provide temporary credentials without placing production long-lived keys in a local file.

Credentials file and AWS config file

The credentials file and config file work together but have different primary purposes.

Aspect	`~/.aws/credentials`	`~/.aws/config`
Primary contents	Access key ID, secret access key, and session token	Region, output format, role settings, and other CLI or SDK configuration
Default profile syntax	`[default]`	`[default]`
Named profile syntax	`[development]`	`[profile development]`
Typical settings	Authentication values	`region = us-west-2` and `output = json`
Custom path environment variable	`AWS_SHARED_CREDENTIALS_FILE`	`AWS_CONFIG_FILE`

For a named profile, the names match conceptually even though the section syntax differs:

[development]
aws_access_key_id = EXAMPLEDEVKEY
aws_secret_access_key = EXAMPLEDEVSECRET

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

The credentials section supplies authentication, while the matching config section supplies region and output preferences. Do not write [profile development] in the credentials file when the standard format expects [development].

Credential resolution and precedence

The credential provider chain is the ordered set of sources an AWS tool examines to obtain credentials. Exact ordering can vary by tool and SDK, but practical sources include explicit settings, environment variables, shared profile files, and runtime identity services.

Environment variables can override credentials you expected to come from a profile.
--profile development explicitly selects a profile for that command.
AWS_PROFILE=development selects a named profile for processes in that shell environment.
Without explicit selection, tools generally use the default profile when the selected provider reaches the shared files.
On AWS compute services, an EC2 instance role or container task role may supply credentials without a local file.
Federated and IAM Identity Center sign-in flows can supply temporary credentials through their own provider mechanisms.

When diagnosing an unexpected identity, inspect AWS-related environment variables and the execution context. A shell, IDE, CI runner, credential helper, instance role, or container task role may be supplying credentials instead of the local profile.

Common credential sources and selection considerations

Source	Typical Use Case	Lifetime	Recommended Use	Common Pitfall
Environment variables	Short-lived local tests or CI injection	Depends on supplied values	Use controlled secret injection; avoid persistent shell configuration	Silently overrides the intended profile
Shared credentials file	Local CLI and SDK development	Long-lived or temporary	Use least privilege and restrictive permissions	Accidental source-control or chat disclosure
IAM Identity Center or federated sign-in	Human access across accounts	Usually temporary	Prefer for workforce access	Expired cached session or wrong account selection
Assumed role credentials	Cross-account or elevated, time-limited work	Temporary	Prefer over production user keys	Missing trust permission or expired session
EC2 instance role	Applications running on EC2	Rotated temporary credentials	Prefer for EC2 workloads	Wrong instance role or blocked metadata access
Container task role	Applications running in a container service	Rotated temporary credentials	Prefer for container workloads	Task role not attached or endpoint unavailable

Security practices

Treat access key IDs, secret access keys, and session tokens as secrets.
Never commit ~/.aws/credentials or copied credential files to source control.
Never paste credential contents into tickets, logs, screenshots, chat, or diagnostic output.
Use least-privilege IAM policies and separate profiles for separate accounts, environments, or roles.
Set restrictive filesystem permissions, such as chmod 600 ~/.aws/credentials on Unix-like systems.
Rotate, disable, or revoke exposed or obsolete access keys immediately through an approved process.
Prefer IAM roles, IAM Identity Center, federated access, and other temporary credential methods over persistent user access keys when feasible.
Verify the account and role before destructive or production commands.

Verification with AWS STS

AWS STS provides identity-related operations. The caller-identity request shows the account, user or role ARN, and principal ID associated with the credentials actually used.

aws sts get-caller-identity --profile development

Run the command without --profile to test the currently selected default or environment-driven identity. For sensitive workflows, use a profile-specific command and compare the returned account and ARN with your expectation.

Diagnosis and troubleshooting

Symptom or Error	Likely Cause	How to Verify	Resolution
Unable to locate credentials	Missing file, unusable profile, wrong custom path, or different user/home directory	Check `AWS_PROFILE`, `AWS_SHARED_CREDENTIALS_FILE`, the effective path, and the process user	Correct the path or profile, provide valid credentials, then run STS caller identity
Profile not found	Misspelled section, absent profile, or a different credentials file is selected	Compare the requested name with the INI section and inspect the selected file path	Correct the profile name or create it in the file being read
Invalid client token or access key	Mismatched key pair, deactivated key, corruption, or overriding environment credentials	Check provider precedence and compare only redacted identifiers with IAM records	Remove the bad source and provision replacement credentials through an approved process
Expired token	Temporary credentials expired, session token missing, or inaccurate local clock	Check expiration, confirm all three fields, and verify time synchronization	Refresh or reauthenticate and update the complete temporary credential set
Access denied	Valid identity lacks permissions, or a policy, boundary, service control policy, resource policy, or explicit deny blocks the action	Run caller identity and review applicable IAM and resource policies	Fix authorization policy or use the correctly authorized role; changing credential formatting will not solve it
Unexpected account identity	Default profile used, environment override, or IDE, CI, helper, or runtime role supplied another identity	Run caller identity with an explicit profile and inspect AWS environment variables	Use explicit profile selection and remove or correct the unintended credential source

Authentication versus authorization

Authentication answers, “Who are these credentials?” Missing credentials, invalid keys, and expired tokens are authentication problems. Authorization answers, “What may this authenticated identity do?” An AccessDenied response after caller identity succeeds usually indicates an authorization problem.

Practical profile workflows

Default local development profile

aws configure
aws sts get-caller-identity

The first command configures the default profile. The second confirms which identity the CLI uses without an explicit profile.

Separate development and production profiles

aws configure --profile development
aws configure --profile production

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

Use separate profiles to make account boundaries visible and reduce the chance of running a development command against production. Confirm both identities before using them.

Temporary session profile

[development]
aws_access_key_id = EXAMPLETEMPACCESSKEY
aws_secret_access_key = EXAMPLETEMPSECRETKEY
aws_session_token = EXAMPLESESSIONTOKEN

This profile works only until the temporary session expires. Refreshing the session must update the access key ID, secret access key, and session token as a consistent set.

Role-based production workflow

A safer production pattern is for a base identity to obtain temporary permissions by assuming an approved role. The resulting temporary credentials can be delivered by a supported sign-in or role provider rather than storing production long-lived keys in the local credentials file.

Exam-relevant notes

The default shared credentials file on Unix-like systems is ~/.aws/credentials.
The default profile section is [default].
A named profile uses [name] in the credentials file but commonly uses [profile name] in the config file.
Temporary credentials require an access key ID, secret access key, and session token.
AWS_PROFILE selects a profile; AWS_SHARED_CREDENTIALS_FILE selects a credentials-file path; AWS_CONFIG_FILE selects a config-file path.
Environment credentials can take precedence over credentials stored in a profile.
aws sts get-caller-identity verifies the identity actually used, while permission errors concern authorization.

Related reference

For the immutable path reference, see AWS shared credentials file.