# aws sts assume-role

AWS CLI commands · Updated 16 November 2026

**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.

## 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

| Situation | Maximum session |
|---|---|
| Default | 1 hour |
| With `--duration-seconds` | Up 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](https://cloudconsole.dev/errors/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 CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CLI Command Reference: sts assume-role](https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role.html)
- [AssumeRole API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)

## Related

- [AccessDenied: User is not authorized to perform: sts:AssumeRole](https://cloudconsole.dev/errors/not-authorized-to-perform-sts-assumerole)
- [How to switch role with the AWS CLI](https://cloudconsole.dev/how-to/switch-role-aws-cli)
- [aws sts get-caller-identity](https://cloudconsole.dev/cli/sts-get-caller-identity)
- [ExpiredToken: The security token included in the request is expired](https://cloudconsole.dev/errors/expiredtoken)
- [aws sts get-session-token](https://cloudconsole.dev/cli/sts-get-session-token)
- [aws sts decode-authorization-message](https://cloudconsole.dev/cli/sts-decode-authorization-message)

---

Source: https://cloudconsole.dev/cli/sts-assume-role

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
