CloudConsole

aws sts decode-authorization-message

Updated 16 November 2026 · How we write and check guides

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.

Terminal running aws sts decode-authorization-message --encoded-message…
A worked example from this page. Copy commands from the text below, not from the image.

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

FieldWhat it tells you
allowedAlways false here.
explicitDenytrue means a Deny statement matched (an SCP, permissions boundary, or identity or resource policy). false means nothing allowed it.
matchedStatementsThe statements that matched, when available, including the policy ID.
context.principalWho made the call.
context.action / context.resourceThe exact action and resource ARN evaluated; often a sub-resource such as a volume or network interface rather than the instance.
context.conditionsEvery 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.
  • 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 app → · Download on the App Store

Sources