APIs: Concepts, Design, Requests, Responses, and Integration

AWS API Credentials

Learn how AWS credentials authenticate API and SDK requests, configure CLI profiles, use IAM roles and STS, rotate keys, and troubleshoot credential errors securely.

AWS credentials are the information that AWS tools and applications use to authenticate API requests. They identify a principal, such as an IAM user, IAM role session, or federated identity.

Authentication answers “Who is making this request?” Authorization answers “What is that principal allowed to do?” After authentication, IAM policies, resource policies, permission boundaries, session policies, and organization controls determine whether the requested action is permitted.

How AWS API authentication works

A CLI command or SDK call obtains credentials from a configured source, uses them to create a signed request, and sends that request to an AWS service. Most AWS API requests use Signature Version 4 (SigV4). AWS validates the credential, signature, request time, region, and service before evaluating authorization policies.

1. A tool or application selects a credential provider.
2. The provider supplies an access key ID, secret access key, and, when required, a session token.
3. The SDK or CLI signs the request.
4. AWS authenticates the principal and evaluates applicable policies.
5. The service returns the result or an authentication or authorization error.

AWS credential types

A long-term access key is a pair: an access key ID and a secret access key. Temporary security credentials contain the same pair plus an AWS_SESSION_TOKEN. The session token must be sent with temporary credentials; the access key and secret alone are incomplete.

IAM users, roles, and the root user

An IAM user can have console credentials, programmatic access keys, or both. A human developer may need an IAM user access key for a legacy tool, but modern human access should use federated sign-in or an approved role where possible.

An IAM role is an identity with permission policies and a trust policy. A trusted principal calls AssumeRole, and AWS Security Token Service (STS) returns a temporary role session. The role's trust policy controls who may assume it; its permission policy controls what the resulting session may do.

Do not create or use root user access keys. The root user has exceptional account authority and is difficult to constrain with normal IAM permissions. Protect the root user with MFA, use it only for tasks that require root access, and use IAM identities for ordinary work.

Creating and managing IAM access keys

In the AWS console, an administrator opens IAM, selects Users, chooses a user, and opens the user's security credentials. Under access keys, the administrator can create a key and select its intended use. Access keys can also be managed with IAM API and CLI commands.

• The secret access key is displayed or downloadable only when it is created. Store it securely immediately; AWS cannot show that same secret again.
• Each key has a status such as Active or Inactive. An inactive key cannot authenticate requests.
• Deactivate a key before deleting it when you need a cautious transition or incident containment.
• Create a replacement, update the dependent system, verify it, then deactivate and delete the old key.
• A user can have at most two access keys. This supports overlapping rotation, not unlimited key storage.

aws iam list-access-keys --user-name example-user
aws iam update-access-key --user-name example-user --access-key-id AKIAEXAMPLE --status Inactive

Configuring the AWS CLI and SDKs

The AWS CLI commonly uses two local files: the shared credentials file for credential values and the shared config file for regions, output formats, role profiles, and other settings. On typical Unix-like systems these are under ~/.aws/credentials and ~/.aws/config. Protect these files with permissions that prevent other local users from reading them.

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

The first command interactively writes a named profile. The second verifies the account, ARN, and principal represented by that profile. The third selects the profile for one command. Keep development and production access in separate profiles and select the intended profile explicitly.

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

A role profile uses credentials from source_profile to call STS and assume the role. The CLI then uses the returned temporary credentials for the command.

export AWS_ACCESS_KEY_ID='...'
export AWS_SECRET_ACCESS_KEY='...'
export AWS_SESSION_TOKEN='...'
export AWS_REGION='us-east-1'
aws sts get-caller-identity

Environment variables are useful for a temporary local session or automation, but they can leak through shell history, process inspection, diagnostic output, or logs. Unset them when finished. AWS_PROFILE selects a named profile when environment credentials are not taking precedence.

Credential precedence depends on the AWS CLI or SDK and its version, but explicit command options and environment variables commonly override profile settings. A typical provider chain checks environment variables, web identity credentials, shared configuration and credentials files, container task credentials, and EC2 instance metadata. The exact order varies, so verify the documentation for the client in use and inspect which source is active rather than guessing.

• AWS_ACCESS_KEY_ID: access key ID.
• AWS_SECRET_ACCESS_KEY: secret access key.
• AWS_SESSION_TOKEN: required for temporary credentials.
• AWS_REGION: default request region.
• AWS_PROFILE: selected named profile.

STS, AssumeRole, and temporary credentials

AWS Security Token Service (STS) issues temporary security credentials. AssumeRole is used for cross-account access, delegated administration, deployment pipelines, and privilege separation.

aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/ReadOnlyRole \
  --role-session-name local-test

The response contains an access key ID, secret access key, session token, and expiration time. Do not treat these values as permanent configuration. Use an SDK or CLI role provider that refreshes them automatically before expiration.

For cross-account access, the target role's trust policy must trust the source principal. The source principal also needs permission to call sts:AssumeRole. The role's permission policy then grants actions in the target account.

• Session policies can further restrict a role session; they do not grant permissions beyond the role's effective permissions.
• An external ID helps a third-party service distinguish a customer-specific delegation and can reduce confused-deputy risk.
• Source identity can associate a role session with the initiating identity for auditing.
• A role trust policy can require MFA for assumption when sensitive human access needs it.
• Web identity federation exchanges an external workload identity token for AWS role credentials, avoiding static keys in CI systems, Kubernetes workloads, or other supported identity environments.

Credentials for compute workloads

Use workload identity instead of putting access keys in application settings, source code, startup scripts, or images.

• Amazon EC2: attach an IAM role through an instance profile. The EC2 credential provider obtains temporary credentials from the instance metadata service, and supported SDKs refresh them.
• Amazon ECS: assign an IAM task role. ECS makes temporary credentials available to the task through the task credential endpoint. Use the task role for application calls rather than the task execution role.
• AWS Lambda: assign an execution role. The Lambda runtime supplies credentials through the standard provider chain.
• External or containerized workloads: use web identity federation or the platform's workload identity mechanism. Do not bake credentials into container layers, deployment manifests, or image environment variables.

For an EC2 application, remove hard-coded keys, attach an instance profile containing only required permissions, and let the SDK's default provider chain retrieve and refresh temporary credentials. The same design applies to ECS task roles and Lambda execution roles.

Credential security practices

• Never commit secrets to source control, package files, container images, logs, issue reports, browser code, or client-side applications. Anything delivered to a client can be copied by its user.
• Use secret scanning in repositories, pre-commit checks, CI pipelines, and image registries.
• If a secret is exposed, remove it from the current files and repository history, but assume it is compromised. Deactivate or replace the credential immediately.
• Prefer eliminating long-term keys rather than merely rotating them. When they are unavoidable, assign an owner, purpose, expiration review date, and minimal policy.
• Restrict local credential files with appropriate operating-system permissions and avoid sharing home directories or build logs.
• Require MFA for sensitive human access and use condition keys in IAM policies where appropriate.
• Use AWS CloudTrail to audit API activity and IAM Access Analyzer to identify unintended access and policy exposure.
• Use AWS Secrets Manager or Systems Manager Parameter Store for application secrets that genuinely cannot be replaced by a role. These services store values; they do not make an overprivileged application safe.

Credential lifecycle and incident response

1. Inventory: list IAM users, access keys, role sessions, workload roles, owners, applications, and accounts.
2. Assess: identify unused, old, overprivileged, shared, or anomalous credentials. Review access-key last-used information and CloudTrail events.
3. Contain: deactivate an exposed access key. If necessary, restrict the related principal while investigating.
4. Replace: create a replacement only when needed, update every dependent application, and verify with aws sts get-caller-identity or an equivalent SDK check.
5. Remove: delete the exposed or unused key after the replacement is confirmed.
6. Investigate: review CloudTrail activity for unexpected regions, services, source addresses, role assumptions, resource changes, and data access. Revoke related sessions where applicable and check for persistence.
7. Improve: reduce permissions, add detection, document ownership, and migrate the workload to a role or federation.

Example: rotating a leaked IAM user key

# Identify the user's keys
aws iam list-access-keys --user-name example-user

# Create a replacement through the IAM console or approved automation.
# Update the dependent system and verify its AWS API calls.

# Contain the exposed key
aws iam update-access-key \
  --user-name example-user \
  --access-key-id AKIAEXAMPLE \
  --status Inactive

# Delete the old key after verification
aws iam delete-access-key \
  --user-name example-user \
  --access-key-id AKIAEXAMPLE

Common authentication failures

Practical design checklist

• Can the workload use an EC2 instance profile, ECS task role, Lambda execution role, or web identity instead of a key?
• Is every human and machine principal uniquely identifiable and assigned an owner?
• Are production and development access separated with named profiles or roles?
• Are permissions limited by actions, resources, conditions, and session duration?
• Are MFA, CloudTrail, IAM Access Analyzer, and secret scanning enabled where appropriate?
• Can the team deactivate, replace, and audit a credential without guessing which systems depend on it?

Exam-relevant notes

• Authentication is identity verification; authorization is policy evaluation.
• Temporary credentials require all three values: access key ID, secret access key, and session token.
• IAM roles are preferred for AWS workloads because they provide temporary, refreshable credentials.
• A role trust policy determines who may assume a role; a permission policy determines what the role may do.
• Root access keys should not be created.
• An AccessDenied response usually indicates authorization failure, not absent credentials.
• A user can have no more than two IAM access keys, allowing a create-update-deactivate-delete rotation sequence.