aws sts decode-authorization-message
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:DecodeAuthorizationMessageyou getAccessDenied; 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.
RunInstanceschecks 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.
- 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.
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 app → · Download on the App Store