Internal Api

AWS Credentials and Authentication for APIs

Learn how AWS credentials authenticate API requests, how SDKs and the CLI find credentials, and how to use temporary roles, profiles, Identity Center, and secure workload authentication.

AWS credentials let the AWS CLI, SDKs, and API clients prove which AWS principal is making a request. After authentication, AWS evaluates IAM policies and related controls to decide whether that principal is authorized to perform the requested action.

This lesson covers credential types, profiles, provider chains, AWS STS, IAM roles, request signing, secure local development, workload identity, and troubleshooting.

Authentication and authorization

Authentication answers: “Who is making this request?” Credentials identify a principal, such as an IAM user, IAM role session, federated workforce user, or AWS service workload.

Authorization answers: “What may that principal do?” IAM policies are JSON documents that allow or deny actions on resources, optionally under conditions. Organization controls, permission boundaries, session policies, resource policies, and explicit denies can also affect the final decision.

Most AWS API requests use AWS Signature Version 4 (SigV4). The client uses credentials to calculate a signature over request information. AWS validates that signature and then evaluates permissions. Credentials therefore do not grant permissions by themselves; they identify the principal whose policies are evaluated.

AWS credential types

An access key ID is the public identifier portion of a programmatic credential. A secret access key is the confidential value used to sign requests. A session token is an additional value required for temporary credentials.

Long-term IAM user access keys

Lifetime: Until rotated, disabled, or deleted. Typical source: an IAM user. Required fields: access key ID and secret access key. Recommended use: only for justified compatibility cases that cannot use roles or federation. Primary risk: a leaked key can remain usable for a long time.

Temporary security credentials

Lifetime: Limited by an expiration time. Typical source: AWS STS, IAM Identity Center, web identity, or an AWS workload role. Required fields: access key ID, secret access key, session token, and expiration metadata. Recommended use: normal choice for humans, applications, and workloads. Primary risk: exposure before expiration, although the lifetime limits the window.

Role-based credentials

Lifetime: Usually temporary and renewable. Typical source: AssumeRole, an attached AWS service role, Identity Center, or web identity. Required fields: the temporary credential set supplied by the provider. Recommended use: humans, applications, AWS services, and federated identities. Primary risk: excessive role permissions or an overly broad trust policy.

Service-specific credentials

Lifetime and fields: Defined by the service. Typical source: a service-specific setup process. Recommended use: only for that service when no suitable IAM role or standard AWS credential method exists. Primary risk: confusing them with standard access keys. They are not interchangeable with an AWS access key ID, secret access key, and session token.

AWS account passwords and console sign-in credentials are different from access keys. A password is used for interactive console authentication. Access keys are used by programmatic clients. An IAM user can have one, both, or neither, but neither should be treated as a general-purpose application credential.

Core fields and environment variables

  • AWS_ACCESS_KEY_ID: identifies the credential set.
  • AWS_SECRET_ACCESS_KEY: confidential signing value.
  • AWS_SESSION_TOKEN: required with temporary STS credentials.
  • AWS_REGION: default AWS Region for clients and commands; it is not an identity credential.
  • AWS_DEFAULT_REGION: another region configuration variable commonly used by the CLI.

For temporary credentials, all three credential fields must refer to the same session. Combining an access key from one session with a secret or token from another commonly causes invalid-token or signature errors.

export AWS_ACCESS_KEY_ID='TEMPORARY_ACCESS_KEY_ID'
export AWS_SECRET_ACCESS_KEY='TEMPORARY_SECRET_ACCESS_KEY'
export AWS_SESSION_TOKEN='TEMPORARY_SESSION_TOKEN'
export AWS_REGION='us-east-1'

Use placeholders like these in documentation. Avoid putting real values in shell history, shared terminals, persistent environment files, or process definitions that other users can inspect.

Shared credentials and configuration files

AWS tools commonly read two INI-style files:

  • ~/.aws/credentials stores access keys and related credential settings.
  • ~/.aws/config stores regions, output settings, SSO settings, and role-profile configuration.

The default profile is named default. Other profiles are named explicitly. In the credentials file, a profile section is commonly written as [development]. In the config file, non-default profiles commonly use [profile development].

# ~/.aws/credentials
[development]
aws_access_key_id = APPROVED_ACCESS_KEY_ID
aws_secret_access_key = APPROVED_SECRET_ACCESS_KEY

# ~/.aws/config
[profile development]
region = us-east-1
output = json

A profile can instead point to an approved role or Identity Center configuration. For example:

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

The source identity must be permitted to call sts:AssumeRole, and the target role's trust policy must trust that source principal. Profile names are local labels; they do not themselves grant access.

Select a profile with the AWS_PROFILE environment variable or an explicit command option.

export AWS_PROFILE=development
aws s3 ls --profile development

Keep both files private, use restrictive operating-system permissions, and ensure they are outside source control. Never commit them or an environment file containing secrets.

The SDK and CLI credential provider chain

A credential provider chain is the ordered set of sources an SDK or tool checks when it needs credentials. Common sources include:

Explicit client configuration

Typical configuration: credentials passed directly to an SDK client. Best environment: rare tests or tightly controlled integrations. Refresh behavior: depends on the supplied provider. Security consideration: easy to embed accidentally; prefer a provider object or role instead of literal secrets.

Environment variables

Typical configuration: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN. Best environment: short-lived local experiments or controlled processes. Refresh behavior: generally none unless the process replaces them. Security consideration: can override the profile you intended to use.

Shared profiles

Typical configuration: ~/.aws/credentials and ~/.aws/config. Best environment: local development and command-line use. Refresh behavior: may come from a role, Identity Center, or another configured provider. Security consideration: protect files and select profiles explicitly.

Web identity token

Typical configuration: a token file and role settings. Best environment: federated workloads, including supported Kubernetes integrations. Refresh behavior: provider obtains replacement temporary credentials as tokens or sessions change. Security consideration: protect the token and narrowly scope the role trust policy.

Container credentials

Typical configuration: an AWS-supported container credential endpoint. Best environment: ECS tasks and compatible container runtimes. Refresh behavior: SDK requests refreshed credentials from the runtime. Security consideration: do not expose the endpoint or task role to unrelated containers.

EC2 instance metadata

Typical configuration: an IAM role attached through an instance profile. Best environment: EC2. Refresh behavior: SDK retrieves and refreshes role credentials. Security consideration: restrict metadata access and use a narrowly scoped role.

Exact precedence differs by SDK, SDK version, language, and configuration. A stale environment variable can win over a correct profile. Explicit SDK credentials can also bypass the normal profile or workload provider. Inspect the active identity instead of assuming which source was selected.

Profile chaining and role assumption

A profile can use another profile as its source and assume a target role. The chain may begin with static local credentials, Identity Center, or another supported source. Each role assumption creates a new temporary session. Keep chains short and document which principal starts the chain.

Temporary credentials and AWS STS

AWS Security Token Service (STS) issues temporary security credentials and supports role assumption. Temporary credentials are preferred because they expire, can be scoped to a specific role session, and avoid embedding a permanent secret in an application.

A temporary session has an expiration time and a session duration. Providers may refresh credentials automatically before expiration. A process that caches credentials without a refresh mechanism will eventually fail.

AssumeRole concepts

  • Source identity: the authenticated principal requesting the role session.
  • Target role: the IAM role to be assumed.
  • Caller permission: the source must be allowed to call sts:AssumeRole on the target role.
  • Trust policy: the target role must trust the source principal and satisfy any conditions.
  • Permission policy: policies attached to the target role determine what the assumed session may do.
  • Role session name: a label recorded with the assumed session for identification and auditing.
  • External ID: an optional condition value often used to reduce confused-deputy risk in third-party access.

Common STS entry points include AssumeRole, AssumeRoleWithWebIdentity, and federation-oriented flows. When signing with STS credentials, the session token must be sent along with the access key ID and secret access key.

IAM roles for AWS compute

Applications running on AWS should normally use an IAM role rather than static access keys. The SDK obtains temporary credentials from the runtime provider and refreshes them automatically when supported.

EC2

Recommended identity mechanism: an IAM role attached through an instance profile. Credentials are delivered through the instance metadata credential provider. Do not store access keys on the instance or bake them into an image.

ECS

Recommended identity mechanism: an ECS task role for application calls. Credentials are delivered through the container credential endpoint. Do not pass access keys as image build arguments or static environment variables.

EKS

Recommended identity mechanism: IAM roles for service accounts or the current supported EKS workload identity mechanism. Credentials are delivered through web identity or the supported workload provider. Do not give every pod a broad node role or share a static key.

Lambda

Recommended identity mechanism: a Lambda execution role. Credentials are delivered to the runtime through the Lambda execution environment and SDK provider chain. Do not embed keys in deployment packages or environment variables.

Other AWS services

Recommended identity mechanism: the service's supported execution or resource role. Credentials are delivered by the service. Do not assume that a console password or service-specific credential can authenticate ordinary AWS API calls.

Use separate workload roles where practical. Grant only the actions and resource ARNs required by each application.

Human access with IAM Identity Center

IAM Identity Center provides workforce sign-in and single sign-on for AWS accounts and applications. It is generally preferable to issuing daily-use IAM user access keys to human users.

A configured CLI profile contains the organization's Identity Center settings. A user signs in, obtains a cached session, and selects the profile for CLI commands. Supported SDKs can use the same Identity Center profile through their credential provider chain.

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

Organizations may also use an external identity provider and federation. Follow the organization's approved sign-in, MFA, account assignment, and permission-set process.

Request signing with SigV4

SigV4 derives a signing key from the secret access key and binds the request to the request date, AWS Region, service name, selected headers, and payload-related data. AWS uses the resulting signature to detect altered requests and verify that the caller possessed the secret at signing time.

Clock accuracy matters because signed requests contain time information and have a limited validity window. The endpoint's region and service name must also match the request. A request sent to the wrong regional endpoint can fail even when the credentials are valid.

Use the AWS CLI or an AWS SDK instead of implementing SigV4 manually. Manual signing is easy to break by changing a header, payload, endpoint, or canonicalization step after signing. SigV4a is a specialized variant for some multi-Region scenarios; use it only when the relevant service and SDK support require it.

Safe local credential configuration

Verify the active identity first

aws sts get-caller-identity

The response includes the AWS account, principal ID, and ARN. It does not reveal secret key material. Run this before testing permissions or deploying resources.

Configure a named profile

aws configure --profile development

Use approved credentials or the organization's supported sign-in flow. Do not include real credential values in instructional material. Prefer a named profile over silently changing the default identity, and use the profile explicitly:

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

For a temporary shell selection:

export AWS_PROFILE=development
aws sts get-caller-identity
unset AWS_PROFILE

Use roles or Identity Center first. Create IAM user access keys only for a justified compatibility need. If long-term keys are unavoidable, keep them narrowly permissioned, monitor their use, rotate them, and disable unused keys.

Safe long-term key rotation

  1. Create a replacement key while the old key still works.
  2. Update the approved consumer securely and test it.
  3. Monitor activity to confirm the consumer uses the replacement.
  4. Disable the old key, observe for failures, then delete it.
  5. Remove old copies from local files, systems, and secret stores.

For an exposed key, treat the event as a security incident: disable or rotate it immediately, inspect CloudTrail and other activity records, assess the permissions and affected resources, remove copies from every location, and improve scanning and role-based access.

Secure credential management

  • Prefer short-lived credentials from roles, STS, Identity Center, or workload identity.
  • Apply least privilege: only the required actions, resources, conditions, and session duration.
  • Never hard-code credentials in source code, client-side applications, container images, logs, tickets, or documentation.
  • Do not commit credential files or environment files containing secrets.
  • Use MFA and organizational controls for sensitive human access paths.
  • Use a secret manager when an application genuinely needs to retrieve an application secret. A stored database password is different from the AWS runtime credentials an SDK should obtain from its role.
  • Rotate or disable exposed and unused long-term access keys.

Credential troubleshooting

Unable to locate credentials

Likely cause: no provider is configured, the wrong profile is selected, a file is unreadable, or a workload has no attached role. Verify environment variables, AWS_PROFILE, profile files, and the workload's role assignment. Then run aws sts get-caller-identity.

The security token included in the request is invalid

Likely cause: an expired, disabled, deleted, or mistyped credential; a missing session token; or fields from different sessions. Obtain a fresh complete set and ensure all three temporary credential fields match.

ExpiredToken or expired session

Likely cause: temporary credentials expired or a provider cannot refresh them. Renew the Identity Center or role session, and restart or correct an application that cached credentials without refresh.

AccessDenied

Likely cause: authentication succeeded but an allow is missing, or an explicit deny, permission boundary, service control policy, resource policy, session policy, or condition blocks access. Check the STS ARN, action, resource, region, account, and applicable policies.

AssumeRole is denied

Likely cause: the caller lacks sts:AssumeRole, the target trust policy does not trust the caller, or a required external ID, MFA condition, tag, source identity, or organization condition is missing. Check both caller permissions and the target trust relationship.

SignatureDoesNotMatch or request time errors

Likely cause: wrong secret, missing session token, wrong endpoint region, wrong service name, changed signed fields, or clock drift. Synchronize the clock and prefer the CLI or SDK over manual signing.

A correct profile appears to be ignored

Likely cause: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or AWS_SESSION_TOKEN overrides the profile; AWS_PROFILE selects another profile; or the application supplies explicit credentials. Inspect and clear unintended variables, confirm profile selection, and verify with STS.

CLI debug output can help reveal provider and request configuration, but use it carefully. Debug logs may expose sensitive request information or identifiers. Do not paste unrestricted debug output into public tickets or chat.

Authentication versus authorization: a practical diagnostic sequence

  1. Check the selected profile and inspect relevant environment variables.
  2. Run aws sts get-caller-identity with the same profile or process environment.
  3. If identity lookup fails, fix credential discovery, expiration, session-token, or clock problems first.
  4. If identity lookup succeeds but the operation is denied, evaluate IAM, resource, organization, boundary, and session policies.
  5. For role assumption, verify both the source permission and target trust policy.
  6. For a regional request, verify the configured region, service endpoint, resource ARN, and system clock.

Exam-relevant notes

  • Authentication identifies a principal; authorization evaluates permissions.
  • Temporary STS credentials require an access key ID, secret access key, and session token.
  • IAM roles are preferred over static keys for EC2, ECS, EKS, Lambda, and other supported workloads.
  • An EC2 instance profile supplies a role to an instance; an ECS task role supplies credentials to a task.
  • AssumeRole requires both source-side permission and target-role trust.
  • Environment variables can unexpectedly override a profile.
  • Correct identity does not imply permission to perform every action.
  • Wrong regions, clock drift, and altered signed requests can cause signing failures.

For related IAM credential concepts, see IAM credentials.