--- cuppy_hub: aws cuppy_path: reference/sts/credential-sources.md cuppy_section: docs cuppy_doc: RG3C-GB4F cuppy_doc_uuid: fb888e58-cd4c-4f7b-a3e2-7f8af1250a2b cuppy_permalink: https://cuppy.io/aws/d/RG3C-GB4F cuppy_version: 4 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/aws/docs/reference/sts/credential-sources cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: c6b3635bcb1ec2c3faa818f7ce802492c84810ef7d44b840cc0e0a1a16baeb08 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # Where credentials come from **The SDKs and the CLI search a fixed list of sources and stop at the first one that returns credentials.** If the identity is wrong, an earlier source in the list is shadowing the one you meant. Prove the identity before debugging anything else: ``` aws sts get-caller-identity --debug ``` In code, call `GetCallerIdentity` with the same client configuration your code uses. The CLI's debug output names the source it used. ## Precedence of settings For every setting, a value set directly in code wins, then an environment variable, then the shared `config` file. So an explicit `credentials` object passed to a client ignores the chain entirely, and an `AWS_ACCESS_KEY_ID` in the environment beats any profile. ## The default chain in Node.js (AWS SDK for JavaScript v3) Checked in this order: 1. **Environment variables** — `fromEnv()`: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`. Never refreshed by anything; the most common cause of stale or wrong identity. 2. **IAM Identity Center** — `fromSSO()`: an SSO profile, using the token from `aws sso login`. 3. **Shared config and credentials files** — `fromIni()`: the selected profile, or `default` when none is selected, which can itself resolve to access keys, an assumed role (`role_arn` with `source_profile`), a web identity token, container credentials, instance metadata, a credential process, Identity Center, or console login. 4. **Console login** — `fromLoginCredentials()`: credentials from `aws login`. 5. **Credential process** — `fromProcess()`: an external command named in the profile. 6. **Web identity token file** — `fromTokenFile()`: an OIDC token file plus a role ARN, exchanged through STS. 7. **Container credentials** — `fromContainerMetadata()`: Amazon ECS task role. 8. **Instance metadata** — `fromInstanceMetadata()`: the EC2 instance profile role. Other SDKs and the CLI follow the same idea with their own order; check the SDK's own guide when it matters. ## What each source reads, and where it caches | Source | Configured in | Cache | Lifetime | |---|---|---|---| | Access keys | env vars, `~/.aws/credentials` | none | until the key is deleted or deactivated | | Assumed role (`role_arn`) | `~/.aws/config` profile | CLI: `~/.aws/cli/cache` | per session; refreshed automatically | | IAM Identity Center | `~/.aws/config`: `[profile]` with `sso_session`, `sso_account_id`, `sso_role_name`; `[sso-session]` with `sso_start_url`, `sso_region` | `~/.aws/sso/cache` | role credentials renew automatically while the Identity Center sign-in is valid; then `aws sso login` again | | Console login (`aws login`) | `~/.aws/config`: `login_session` | `~/.aws/login/cache` (override with `AWS_LOGIN_CACHE_DIRECTORY`) | short-term credentials last 15 minutes and refresh automatically for up to 12 hours; then `aws login` again | The legacy Identity Center profile form (`sso_start_url` directly in the profile, no `sso-session` section) does not refresh tokens automatically; prefer the `sso-session` form. `aws login` requires AWS CLI 2.32.0 or later. The SDK login provider is supported in the SDK for JavaScript 3.x but not 2.x, and in Boto3 only with CRT installed; check the SDK reference table for others. ## How the wrong identity happens - **A leftover environment variable** from an earlier `export` or a CI secret beats your profile. Check: `printenv | grep AWS` (Linux, macOS) or `set AWS` (Windows), then unset. - **The wrong profile.** No profile was selected, so `default` was used. Check: `aws configure list --profile `. - **A stale cache** after changing role or account. Clear `~/.aws/cli/cache` (assumed roles) or sign out with `aws sso logout` (Identity Center). - **Running on EC2 or ECS** with credential environment variables or a profile also present: those come earlier in the chain and win over the instance or task role. - **Credentials passed in code** silently override everything, including a correctly configured profile. Each of these appears to the caller as `InvalidClientTokenId`, `ExpiredToken`, or an access denied error naming an unexpected principal. Fixes by error: `reference/sts/errors.md`. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.