CloudConsole

aws sts assume-role

Updated 16 November 2026 · How we write and check guides

Short answer

aws sts assume-role --role-arn arn:aws:iam::123456789012:role/Admin --role-session-name jane returns temporary credentials (access key, secret key and session token) for that role, valid for an hour by default. For everyday CLI use, a profile with role_arn and source_profile does the same thing automatically and refreshes it for you.

Terminal running read AK SK ST <<<"$(aws sts assume-role \ with its example output
A worked example from this page with its output. Copy commands from the text below, not from the image.

What the command does

assume-role exchanges your current credentials for short-lived credentials of another role, in the same or another account. Two things must both allow it: the role's trust policy must name your principal (or account), and your own identity must be allowed sts:AssumeRole on that role ARN.

Syntax

aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/Admin \
  --role-session-name jane-debug \
  [--duration-seconds 3600] \
  [--external-id abc123] \
  [--serial-number arn:aws:iam::111122223333:mfa/jane --token-code 123456]

Response (trimmed):

{
  "Credentials": {
    "AccessKeyId": "ASIA...",
    "SecretAccessKey": "...",
    "SessionToken": "...",
    "Expiration": "2026-11-16T11:02:00+00:00"
  },
  "AssumedRoleUser": { "Arn": "arn:aws:sts::123456789012:assumed-role/Admin/jane-debug" }
}

Worked examples

Export the credentials into your shell:

read AK SK ST <<<"$(aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/Admin --role-session-name jane-debug \
  --query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' --output text)"
export AWS_ACCESS_KEY_ID=$AK AWS_SECRET_ACCESS_KEY=$SK AWS_SESSION_TOKEN=$ST
aws sts get-caller-identity

Undo it with unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN.

Better for daily use: a role profile in ~/.aws/config, which the CLI assumes and refreshes on demand:

[profile prod-admin]
role_arn = arn:aws:iam::123456789012:role/Admin
source_profile = default
role_session_name = jane
mfa_serial = arn:aws:iam::111122223333:mfa/jane
duration_seconds = 3600
aws s3 ls --profile prod-admin

Third-party access with an external ID:

aws sts assume-role --role-arn arn:aws:iam::123456789012:role/VendorAudit \
  --role-session-name vendor --external-id 7f3c2b9e

Assume a role with a web identity token (for example from a CI provider's OIDC token), which needs no AWS credentials beforehand:

aws sts assume-role-with-web-identity \
  --role-arn arn:aws:iam::123456789012:role/GitHubDeploy \
  --role-session-name ci-4821 \
  --web-identity-token "$OIDC_TOKEN"

Duration rules

SituationMaximum session
Default1 hour
With --duration-secondsUp to the role's maximum session duration, which can be set up to 12 hours
Role chaining (assuming a role from a role session)1 hour, regardless of settings

Gotchas

  • AccessDenied ... is not authorized to perform: sts:AssumeRole means either the trust policy or your IAM policy is missing; see not authorized to perform sts:AssumeRole. An SCP or a missing external ID or MFA condition gives the same message.
  • Stale variables. Assuming a role while old AWS_SESSION_TOKEN values are exported leads to InvalidClientTokenId. Unset them first.
  • Session names show up in CloudTrail. Use something that identifies the person or job, not a constant like session.
  • Do not paste credentials into tickets or chat. They are live until they expire.
  • Trace people through shared roles. Values passed with --source-identity and session tags with --tags are recorded in CloudTrail and can be used in policy conditions, which helps when many people use the same role.

Questions

How do I assume a role from the AWS CLI?

Either run aws sts assume-role and export the returned credentials, or define a profile with role_arn and source_profile and use --profile, which is simpler and refreshes automatically.

Why does assume-role say the security token included in the request is invalid?

The credentials used to call assume-role are bad: a deleted key, or an expired session token still set in your environment.

How do I assume a role with web identity from the CLI?

Use aws sts assume-role-with-web-identity with --role-arn, --role-session-name and --web-identity-token; no existing AWS credentials are needed.

When this happens away from your desk

Switching into a production role is a deliberate step, and it should feel like one on any device. CloudConsole, a phone app for AWS, is built with production guardrails and a clear view of which account and role you are using.

About the app → · Download on the App Store

Sources