AWS STS Temporary Credentials Explained

Simple explanation

STS is a global AWS service that hands out short-lived credentials on demand. Instead of giving a person or application a permanent password, STS creates a temporary badge that works for a set period and then stops working automatically.

The relationship between IAM users, IAM roles, and STS works like this:

• An IAM user has permanent credentials (an access key pair). These credentials identify a specific person or service account and do not expire on their own.
• An IAM role has no permanent credentials. A role defines what permissions are available, but nothing can use those permissions until someone assumes the role.
• STS is the bridge. When a user, service, or external identity assumes a role, STS checks the role’s trust policy, and if allowed, issues temporary credentials scoped to that role’s permissions.

The result is that the caller gets time-limited access without anyone storing long-term secrets.

Why STS matters

Temporary credentials are safer than long-lived access keys for one core reason: they expire. A leaked temporary credential is useful to an attacker only until the session ends. A leaked access key is useful until someone notices and revokes it, which could be hours, days, or months.

• No rotation required. Long-lived keys must be rotated on a schedule. Temporary credentials rotate themselves every time a new session starts.
• No revocation delay. If you suspect a compromise, the credential expires on its own. You can also revoke all sessions for a role immediately through IAM.
• Scoped permissions. Each STS session can be further restricted with session policies, limiting what the temporary credentials can do beyond the role’s base permissions.
• Audit trail. Every STS call is logged in CloudTrail, so you can trace exactly who assumed which role and when.

How STS works

The flow from request to API call follows these steps:

1. A caller requests temporary credentials. The caller can be an IAM user, another role, or an external identity (like a GitHub Actions workflow). The request goes to the STS API with details about which role to assume.
2. STS checks the trust policy. The target role has a trust policy that lists who is allowed to assume it. STS verifies the caller’s identity against that policy. If the caller is not listed, the request is denied.
3. STS issues temporary credentials. If the trust check passes, STS generates a fresh set of credentials: an access key ID, a secret access key, and a session token. These credentials have a fixed expiration time.
4. The caller uses the temporary credentials. The caller includes all three credential components when making AWS API calls. AWS validates the credentials and checks the role’s permissions policy for each request.
5. The credentials expire. After the session duration elapses, the credentials stop working. The caller must request new credentials to continue.

What temporary credentials contain

Every set of temporary credentials from STS contains three components:

• Access Key ID starts with ASIA, which distinguishes it from long-lived user keys that start with AKIA. See access keys explained for more on key prefixes.
• Secret Access Key is used to sign API requests, just like a permanent secret key.
• Session Token is a long string that must accompany every API request. AWS uses it to validate the temporary session and link it back to the assumed role.

Main STS operations

AssumeRole

AssumeRole is the most commonly used STS API. It exchanges your current credentials for temporary credentials that belong to a different IAM role. AWS checks the target role’s trust policy, and if your identity is allowed, issues a new set of credentials scoped to that role’s permissions.

aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/DeployRole \
  --role-session-name "deploy-session"

The response includes the three credential components plus an expiration timestamp:

{
  "Credentials": {
    "AccessKeyId": "ASIAEXAMPLE",
    "SecretAccessKey": "wJalrXUtnFEMI/EXAMPLEKEY",
    "SessionToken": "AQoDYXdzEJr...(truncated)",
    "Expiration": "2026-01-15T12:00:00Z"
  },
  "AssumedRoleUser": {
    "AssumedRoleId": "AROAEXAMPLE:deploy-session",
    "Arn": "arn:aws:sts::123456789012:assumed-role/DeployRole/deploy-session"
  }
}

To use these credentials in your terminal, export them as environment variables:

export AWS_ACCESS_KEY_ID="ASIAEXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFEMI/EXAMPLEKEY"
export AWS_SESSION_TOKEN="AQoDYXdzEJr...(truncated)"

# Verify the assumed identity
aws sts get-caller-identity

By default, AssumeRole sessions last 1 hour. You can request up to the role’s MaxSessionDuration setting (configurable up to 12 hours) using the —duration-seconds flag. For the full mechanics of role assumption including trust policies and cross-account patterns, see role assumption in AWS.

GetSessionToken

GetSessionToken returns temporary credentials for your own IAM user identity, without switching to a different role. The main use case is satisfying MFA requirements.

When an IAM policy includes an MFA condition (aws:MultiFactorAuthPresent), regular access key calls fail because they carry no MFA proof. Calling GetSessionToken with your MFA code produces temporary credentials that include MFA context, satisfying the condition.

aws sts get-session-token \
  --serial-number arn:aws:iam::123456789012:mfa/alice \
  --token-code 123456 \
  --duration-seconds 43200

The —serial-number is the ARN of the user’s MFA device. The —token-code is the current 6-digit code from the authenticator app. The session above lasts 12 hours (43200 seconds).

GetCallerIdentity

GetCallerIdentity returns the account ID, ARN, and unique identifier for whichever credentials are currently active. It requires no specific permissions and always succeeds for any valid credential. Use it whenever you need to confirm which identity the CLI or SDK is using.

aws sts get-caller-identity

{
  "UserId": "AROAEXAMPLE:deploy-session",
  "Account": "123456789012",
  "Arn": "arn:aws:sts::123456789012:assumed-role/DeployRole/deploy-session"
}

This is the first command to run when debugging access denied errors. If the ARN is not what you expect, your credentials are pointing to the wrong identity. Check your environment variables, CLI profile, and credential file. See managing IAM with the AWS CLI for how profile resolution works.

AssumeRoleWithWebIdentity and AssumeRoleWithSAML

These two APIs work like AssumeRole but accept an external identity token instead of AWS credentials:

• AssumeRoleWithWebIdentity accepts an OIDC token from providers like GitHub Actions, Google, or Amazon Cognito. This is how CI/CD pipelines and Kubernetes pods get AWS credentials without storing access keys.
• AssumeRoleWithSAML accepts a SAML assertion from corporate identity providers (Okta, Azure AD, ADFS). This is how enterprise SSO users get AWS console and CLI access.

Both follow the same pattern: the role’s trust policy names the external identity provider, and STS verifies the token before issuing temporary credentials. Maximum session duration is 12 hours for both.

When to use STS

Most of the time, STS works behind the scenes without you calling it directly. Here are the common scenarios and how STS fits in.

EC2 instance profiles

When you attach an IAM role to an EC2 instance, AWS calls STS automatically and delivers temporary credentials through the Instance Metadata Service (IMDS). Your application code uses the SDK, which fetches and refreshes these credentials without any STS calls in your code.

Lambda execution roles

Each Lambda function has an execution role. When the function runs, Lambda calls STS to get temporary credentials and injects them as environment variables. Your function code picks them up through the SDK automatically.

ECS and EKS workloads

ECS tasks use task roles, and EKS pods can use IAM Roles for Service Accounts (IRSA). Both mechanisms call STS behind the scenes to deliver scoped temporary credentials to each container or pod.

Cross-account access

When an identity in Account A needs to access resources in Account B, it assumes a role in Account B using AssumeRole. The trust policy on the Account B role grants access to Account A. This is the standard pattern for multi-account setups in AWS Organizations.

GitHub Actions and OIDC federation

CI/CD pipelines can use AssumeRoleWithWebIdentity to get AWS credentials from a GitHub Actions OIDC token. This avoids storing long-lived access keys as repository secrets. The trust policy on the role restricts which repository, branch, or environment can assume it.

MFA-protected operations for IAM users

IAM users who need to perform sensitive operations protected by MFA conditions call GetSessionToken with their MFA code. The resulting temporary credentials carry MFA context, allowing the user to perform actions that require aws:MultiFactorAuthPresent.

STS vs IAM roles vs access keys

The key insight: IAM roles define permissions, and STS provides the credentials to use those permissions. Access keys bypass this system entirely by giving permanent credentials to an IAM user. For why that is a problem in production, see why long-lived access keys are dangerous.

How SDKs find credentials

AWS SDKs (Python/Boto3, JavaScript, Go, Java, .NET, and others) each implement a credential provider chain that checks multiple sources in sequence until it finds valid credentials. The exact order varies by SDK and version, but the common sources across most SDKs include:

• Environment variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN
• Shared credentials and config files at ~/.aws/credentials and ~/.aws/config
• Container credentials used by ECS task roles and EKS pod roles
• Instance metadata on EC2, providing credentials from the instance profile via IMDS