Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Authorization for versions and aliases in Step Functions workflows

Focus mode

On this page

Authorization for versions and aliases in Step Functions workflows - AWS Step Functions

To invoke Step Functions API actions with a version or an alias, you need appropriate permissions. To authorize a version or an alias to invoke an API action, Step Functions uses the state machine’s ARN instead of using the version ARN or alias ARN. You can also scope down the permissions for a specific version or alias. For more information, see Scoping down permissions.

You can use the following IAM policy example of a state machine named myStateMachine to invoke the CreateStateMachineAlias API action to create a state machine alias.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "states:CreateStateMachineAlias", "Resource": "arn:aws:states:us-east-1:123456789012:stateMachine:myStateMachine" } ] }

When you set permissions to allow or deny access to API actions using state machine versions or aliases, consider the following:

Scoping down permissions for a version or alias

You can use a qualifier to further scope down the authorization permission needed by a version or an alias. A qualifier refers to a version number or an alias name. You use the qualifier to qualify a state machine. The following example is a state machine ARN that uses an alias named PROD as the qualifier.

arn:aws:states:us-east-1:123456789012:stateMachine:myStateMachine:PROD

For more information about qualified and unqualified ARNs, see Associating executions with a version or alias.

You scope down the permissions using the optional context key named states:StateMachineQualifier in an IAM policy's Condition statement. For example, the following IAM policy for a state machine named myStateMachine denies access to invoke the DescribeStateMachine API action with an alias named as PROD or the version 1.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "states:DescribeStateMachine", "Resource": "arn:aws:states:us-east-1:123456789012:stateMachine:myStateMachine", "Condition": { "ForAnyValue:StringEquals": { "states:StateMachineQualifier": [ "PROD", "1" ] } } } ] }

The following list specifies the API actions on which you can scope down the permissions with the StateMachineQualifier context key.

PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.