# aws sts decode-authorization-message

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws sts decode-authorization-message --encoded-message <message> --query DecodedMessage --output text turns the long encoded blob in an UnauthorizedOperation error into JSON showing which action was denied, on which resource, whether an explicit deny matched, and the request context. The caller needs sts:DecodeAuthorizationMessage.

## What the command does

Some services, most often EC2, do not explain a permission failure in plain text. Instead you get:

```
An error occurred (UnauthorizedOperation) when calling the RunInstances operation:
You are not authorized to perform this operation. User: arn:aws:sts::123456789012:assumed-role/Dev/jane
is not authorized to perform: ec2:RunInstances ... Encoded authorization failure message: 4mFq...
```

The encoded part hides details such as policy conditions from the caller. This command decodes it for anyone who has been granted `sts:DecodeAuthorizationMessage`.

## Syntax

```
aws sts decode-authorization-message --encoded-message "<encoded string>"
```

The result is a single `DecodedMessage` field containing a JSON string, so pipe it through `jq` or Python to read it.

## Worked examples

**Decode and pretty-print**:

```
aws sts decode-authorization-message --encoded-message "$MSG" \
  --query DecodedMessage --output text | jq .
```

**Capture the message straight from a failing command**:

```
MSG=$(aws ec2 run-instances --image-id ami-0123456789abcdef0 --instance-type t3.micro \
  --dry-run 2>&1 | sed -n 's/.*Encoded authorization failure message: //p')
aws sts decode-authorization-message --encoded-message "$MSG" \
  --query DecodedMessage --output text | jq '{allowed, explicitDeny, action: .context.action, resource: .context.resource}'
```

**Show the conditions in the request**, which is usually where the answer is (a missing tag, the wrong region, an unencrypted volume):

```
aws sts decode-authorization-message --encoded-message "$MSG" \
  --query DecodedMessage --output text | jq '.context.conditions.items[] | {key, values: [.values.items[].value]}'
```

## Reading the decoded JSON

| Field | What it tells you |
|---|---|
| `allowed` | Always `false` here. |
| `explicitDeny` | `true` means a Deny statement matched (an SCP, permissions boundary, or identity or resource policy). `false` means nothing allowed it. |
| `matchedStatements` | The statements that matched, when available, including the policy ID. |
| `context.principal` | Who made the call. |
| `context.action` / `context.resource` | The exact action and resource ARN evaluated; often a sub-resource such as a volume or network interface rather than the instance. |
| `context.conditions` | Every condition key and value in the request: region, tags, encryption flags and more. |

## Gotchas

- **You need permission to decode.** Without `sts:DecodeAuthorizationMessage` you get `AccessDenied`; ask an administrator to decode it or grant the action to your role.
- **Copy the whole message.** It is long and easy to truncate in terminals and chat tools; a partial message fails with `InvalidAuthorizationMessageException`.
- **The denied resource may surprise you.** `RunInstances` checks the AMI, subnet, security group, volume, network interface and key pair separately. The decoded resource tells you which one failed.
- **Not every service encodes errors.** Most return readable messages naming the policy type, such as [no identity-based policy allows the action](https://cloudconsole.dev/errors/accessdenied-no-identity-based-policy-allows).
- **Treat the decoded output as sensitive.** It can reveal policy structure and condition values from your organisation, so share it with the people fixing the problem rather than pasting it into public channels.

## Questions

### How do I decode an encoded authorization failure message?

Run aws sts decode-authorization-message --encoded-message "<message>" --query DecodedMessage --output text and pipe it to jq.

### What permission is needed to decode authorization messages?

sts:DecodeAuthorizationMessage on the calling identity.

### What does explicitDeny true mean?

A Deny statement matched, for example in a service control policy or permissions boundary. Adding an Allow will not fix it; the deny must change.

## When this happens away from your desk

Permission errors during an incident are frustrating when the reason is hidden. CloudConsole, a phone app for AWS, is built to make the identity and account in use clear before you act.

[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 decode-authorization-message](https://docs.aws.amazon.com/cli/latest/reference/sts/decode-authorization-message.html)
- [DecodeAuthorizationMessage API reference](https://docs.aws.amazon.com/STS/latest/APIReference/API_DecodeAuthorizationMessage.html)

## Related

- [UnauthorizedOperation: You are not authorized to perform this operation. Encoded authorization failure message](https://cloudconsole.dev/errors/unauthorizedoperation-encoded-message)
- [AccessDenied with an explicit deny in a service control policy](https://cloudconsole.dev/errors/explicit-deny-service-control-policy)
- [AccessDenied with an explicit deny in a permissions boundary](https://cloudconsole.dev/errors/explicit-deny-permissions-boundary)
- [aws iam simulate-principal-policy](https://cloudconsole.dev/cli/iam-simulate-principal-policy)
- [aws sts get-caller-identity](https://cloudconsole.dev/cli/sts-get-caller-identity)
- [aws sts assume-role](https://cloudconsole.dev/cli/sts-assume-role)

---

Source: https://cloudconsole.dev/cli/sts-decode-authorization-message

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