IAM Toolbox (Preview)

2026/11/16 - IAM Toolbox (Preview) - 1 new1 updated api methods

Changes  AWS IAM adds the GetRequestAuthorizationPolicy operation, per-check authorization results (checks) and extra policy metadata for resource-based policies (policySource) in GetRequestAuthorizationDetails for Access Troubleshooter.

GetRequestAuthorizationPolicy (new) Link ¶

Retrieves a policy that was evaluated for a specific access denied request. The operation returns the structured JSON document of the policy that was captured with the original authorization request. It doesn't retrieve the current version of the policy.

For some AWS services and policy types, the returned policy document includes all actions relevant to the service that processed the denied request, but might omit actions for other services.

Specify the authorization ID from the access denied error message and the policy URI returned by GetRequestAuthorizationDetails for the same authorization ID.

Access depends on the account and organization recorded for the principal that made the denied request. If an organization was recorded, the calling principal must belong to that organization. Otherwise, the calling principal must belong to the recorded account.

To use this operation, you must have the iam:GetRequestAuthorizationPolicy permission.

See also: AWS API Documentation

Request Syntax

client.get_request_authorization_policy(
    authorizationId='string',
    policyUri='string'
)
type authorizationId:

string

param authorizationId:

[REQUIRED]

The authorization ID received in the access denied error message. This ID identifies the request whose evaluated policy you want to retrieve.

type policyUri:

string

param policyUri:

[REQUIRED]

The URI of the policy to retrieve. Use the uri value from the policies list returned by GetRequestAuthorizationDetails for the same authorization ID.

rtype:

dict

returns:

Response Syntax

{
    'policyDocument': {...}|[...]|123|123.4|'string'|True|None
}

Response Structure

  • (dict) --

    • policyDocument (:ref:`document<document>`) --

      The policy document evaluated for the denied request, returned as a JSON object.

      For some AWS services and policy types, this document includes all actions relevant to the service that processed the denied request, but might omit actions for other services.

GetRequestAuthorizationDetails (updated) Link ¶
Changes (response)
{'evaluations': {'checks': [{'checkType': 'SERVICE_CONTROL_POLICY | '
                                          'RESOURCE_CONTROL_POLICY | '
                                          'VPC_ENDPOINT | RESOURCE | PRINCIPAL '
                                          '| PERMISSIONS_BOUNDARY | SESSION',
                             'evaluatedEffect': 'ALLOW | NO_IMPACT | '
                                                'IMPLICIT_DENY | EXPLICIT_DENY',
                             'matchedPolicies': [{'matchedStatements': [{'evaluatedEffect': 'ALLOW '
                                                                                            '| '
                                                                                            'DENY',
                                                                         'sid': 'string'}],
                                                  'uri': 'string'}],
                             'relevantPolicyTypes': ['IDENTITY_BASED_POLICY | '
                                                     'RESOURCE_BASED_POLICY | '
                                                     'PERMISSIONS_BOUNDARY | '
                                                     'SESSION_POLICY | '
                                                     'SERVICE_CONTROL_POLICY | '
                                                     'RESOURCE_CONTROL_POLICY '
                                                     '| VPC_ENDPOINT_POLICY'],
                             'targetArn': 'string'}]},
 'policies': {'policySource': {'string': 'string'}}}

Retrieves the authorization details for a specific access denied request. The details include the request context, the evaluations performed, and the policies that were evaluated.

Use this operation to understand why a request was denied. Supported services include an authorization ID in the access denied error message. Pass that ID to this operation to retrieve the details.

To retrieve the content for a policy in the policies list, call GetRequestAuthorizationPolicy.

Authorization details are available for at least 24 hours after the denial.

To use this operation, you must have the iam:GetRequestAuthorizationDetails permission.

See also: AWS API Documentation

Request Syntax

client.get_request_authorization_details(
    authorizationId='string',
    nextToken='string'
)
type authorizationId:

string

param authorizationId:

[REQUIRED]

The authorization ID received in the access denied error message. This ID identifies the specific request to retrieve details for.

type nextToken:

string

param nextToken:

The pagination token from a previous call, used to retrieve the next page of evaluations. Omit this value on the first call.

rtype:

dict

returns:

Response Syntax

{
    'requestContext': {
        'string': {...}|[...]|123|123.4|'string'|True|None
    },
    'evaluations': [
        {
            'action': 'string',
            'resource': 'string',
            'context': {
                'string': {...}|[...]|123|123.4|'string'|True|None
            },
            'evaluatedEffect': 'ALLOW'|'EXPLICIT_DENY'|'IMPLICIT_DENY',
            'matchedPolicies': [
                {
                    'uri': 'string',
                    'matchedStatements': [
                        {
                            'sid': 'string',
                            'evaluatedEffect': 'ALLOW'|'DENY'
                        },
                    ]
                },
            ],
            'checks': [
                {
                    'checkType': 'SERVICE_CONTROL_POLICY'|'RESOURCE_CONTROL_POLICY'|'VPC_ENDPOINT'|'RESOURCE'|'PRINCIPAL'|'PERMISSIONS_BOUNDARY'|'SESSION',
                    'evaluatedEffect': 'ALLOW'|'NO_IMPACT'|'IMPLICIT_DENY'|'EXPLICIT_DENY',
                    'targetArn': 'string',
                    'relevantPolicyTypes': [
                        'IDENTITY_BASED_POLICY'|'RESOURCE_BASED_POLICY'|'PERMISSIONS_BOUNDARY'|'SESSION_POLICY'|'SERVICE_CONTROL_POLICY'|'RESOURCE_CONTROL_POLICY'|'VPC_ENDPOINT_POLICY',
                    ],
                    'matchedPolicies': [
                        {
                            'uri': 'string',
                            'matchedStatements': [
                                {
                                    'sid': 'string',
                                    'evaluatedEffect': 'ALLOW'|'DENY'
                                },
                            ]
                        },
                    ]
                },
            ]
        },
    ],
    'policies': [
        {
            'type': 'IDENTITY_BASED_POLICY'|'RESOURCE_BASED_POLICY'|'PERMISSIONS_BOUNDARY'|'SESSION_POLICY'|'SERVICE_CONTROL_POLICY'|'RESOURCE_CONTROL_POLICY'|'VPC_ENDPOINT_POLICY',
            'inline': True|False,
            'uri': 'string',
            'attachedTo': [
                {
                    'arn': 'string'
                },
            ],
            'policySource': {
                'string': 'string'
            }
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • requestContext (dict) --

      The request context is the set of context keys and values that apply to the entire request and are shared by all evaluations.

      • (string) --

        • (:ref:`document<document>`) --

    • evaluations (list) --

      The list of evaluations for this request. Each evaluation shows how a single action and resource pair was evaluated. This includes the context, the effect, and any policies that matched.

      • (dict) --

        Represents an individual evaluation for a single action and resource pair. This includes the context, the resulting effect, and any policies that matched.

        • action (string) --

          The action evaluated for this request (for example, iam:PassRole).

        • resource (string) --

          The resource that the action targeted. This is typically a resource ARN, but can be a wildcard ARN that matches multiple resources, or empty for actions that are not resource-specific.

        • context (dict) --

          The context keys and values specific to this evaluation. These are applied on top of the request context.

          • (string) --

            • (:ref:`document<document>`) --

        • evaluatedEffect (string) --

          The result of the evaluation. Valid values:

          • ALLOW - The action was allowed.

          • EXPLICIT_DENY - The action was explicitly denied by a policy.

          • IMPLICIT_DENY - The action was denied because at least one required authorization check had no matching allow statement.

        • matchedPolicies (list) --

          matchedPolicies is deprecated. Use checks instead. This value contains the policies that matched during evaluation of this action and resource.

          • (dict) --

            A policy that matched during evaluation, referenced by URI. The URI corresponds to a policy in the top-level policies list.

            • uri (string) --

              The URI of the policy. This cross-references an entry in the top-level policies list. The value depends on the policy type:

              • For managed policies, this is the policy ARN.

              • For inline policies, this is an opaque identifier.

            • matchedStatements (list) --

              The statements within the policy that matched during the evaluation.

              • (dict) --

                A statement that matched during evaluation.

                • sid (string) --

                  The statement ID (Sid). If the statement has no Sid, one is generated for reference.

                • evaluatedEffect (string) --

                  The evaluated effect of this statement. Valid values:

                  • ALLOW - The statement allows the action.

                  • DENY - The statement denies the action.

        • checks (list) --

          checks contains the authorization checks that explain an evaluation result. Each check is one authorization requirement and reports its result and policies from the top-level policies list with matching statements. The output lists RCP checks from the organization root to the account, then SCP checks from the organization root to the account. It then lists VPC endpoint, resource, principal, permissions boundary, and session checks. When checks is present, an EXPLICIT_DENY evaluation includes an EXPLICIT_DENY check. When checks is present for an IMPLICIT_DENY evaluation, it includes an IMPLICIT_DENY check and no EXPLICIT_DENY check. For more information about how IAM evaluates policies, see Policy evaluation logic.

          PRINCIPAL, PERMISSIONS_BOUNDARY, and SESSION checks appear when they apply to the principal that made the request, even if none of their policies matched. A missing allow produces IMPLICIT_DENY, or NO_IMPACT when another path already allowed the request.

          Returned when the caller is in the request principal's account or organization. The absence of checks does not mean no authorization checks applied.

          • (dict) --

            Represents one authorization requirement considered during an evaluation and its result.

            • checkType (string) --

              The type of requirement that the check evaluates. Valid values:

              • SERVICE_CONTROL_POLICY - The service control policies (SCPs) attached to one organization target, such as a root, organizational unit, or account, that apply to the principal.

              • RESOURCE_CONTROL_POLICY - The resource control policies (RCPs) attached to one organization target that apply to the resource.

              • VPC_ENDPOINT - The VPC endpoint policy for the endpoint through which the request passes.

              • RESOURCE - The resource owner's resource-based policies, when the owner must allow the request separately, such as a cross-account request or a request to an AWS KMS key.

              • PRINCIPAL - The principal's identity-based policies attached to the IAM user or role.

              • PERMISSIONS_BOUNDARY - The permissions boundary on the IAM user or role.

              • SESSION - The role session that made the request, decided by its session policies.

            • evaluatedEffect (string) --

              The result of evaluating this requirement. Valid values:

              • ALLOW - A statement that applies to this check allows the request.

              • EXPLICIT_DENY - A deny statement that applies to this check matches.

              • IMPLICIT_DENY - The check required an allow and nothing that applies to it allows the request.

              • NO_IMPACT - No statement in this check matched, and no allow was needed because another path allowed the request.

            • targetArn (string) --

              The ARN that distinguishes this check from other checks of the same type. This value is absent when the check type alone identifies the check. For SCP and RCP checks, this is the AWS Organizations ARN of the root, organizational unit, or account that the evaluated policies are attached to.

            • relevantPolicyTypes (list) --

              The policy types used to satisfy this check, plus the type of every policy with a statement that matched in it. matchedPolicies lists matching policies in the top-level policies list.

              • (string) --

                The policy type.

            • matchedPolicies (list) --

              Policies in this list have statements that matched for this check. Each URI corresponds to an entry in the top-level policies list. Only policies in the top-level list are included. The check effect can reflect a matched policy omitted from this list, so this list can be empty even when the effect is ALLOW.

              • (dict) --

                A policy that matched during evaluation, referenced by URI. The URI corresponds to a policy in the top-level policies list.

                • uri (string) --

                  The URI of the policy. This cross-references an entry in the top-level policies list. The value depends on the policy type:

                  • For managed policies, this is the policy ARN.

                  • For inline policies, this is an opaque identifier.

                • matchedStatements (list) --

                  The statements within the policy that matched during the evaluation.

                  • (dict) --

                    A statement that matched during evaluation.

                    • sid (string) --

                      The statement ID (Sid). If the statement has no Sid, one is generated for reference.

                    • evaluatedEffect (string) --

                      The evaluated effect of this statement. Valid values:

                      • ALLOW - The statement allows the action.

                      • DENY - The statement denies the action.

    • policies (list) --

      The list of policies that were evaluated.

      • (dict) --

        Contains details about a policy evaluated during authorization. Details include the policy type, whether it is inline or managed, a URI that identifies it, the entities it is attached to, and its source, if present.

        • type (string) --

          The type of policy. Valid values:

          • IDENTITY_BASED_POLICY - An identity-based policy attached to an IAM user, group, or role.

          • PERMISSIONS_BOUNDARY - A permissions boundary for an IAM entity.

          • RESOURCE_BASED_POLICY - A resource-based policy attached to a resource. An AWS service can evaluate and report a policy kind it defines, such as a KMS grant, as RESOURCE_BASED_POLICY. policySource identifies the kind.

          • RESOURCE_CONTROL_POLICY - A resource control policy (RCP) in AWS Organizations.

          • SERVICE_CONTROL_POLICY - A service control policy (SCP) in AWS Organizations.

          • SESSION_POLICY - A session policy passed during role assumption or federation.

          • VPC_ENDPOINT_POLICY - A VPC endpoint policy.

        • inline (boolean) --

          Specifies whether this is an inline policy ( true) or a managed policy ( false).

        • uri (string) --

          A URI that identifies the policy. Use this URI to cross-reference the policy with the matching policies in each evaluation. To retrieve the policy document, pass this URI as the policyUri parameter of GetRequestAuthorizationPolicy, together with the same authorization ID. The value depends on the policy type:

          • For managed policies, this is the policy ARN.

          • For inline policies, which have no ARN, this is an opaque identifier.

        • attachedTo (list) --

          The entities that the policy is attached to. For identity, session, and resource-based policies, this is typically a single entity. For organization control policies (SCPs and RCPs), it can be multiple entities at different levels of the organization hierarchy.

          • (dict) --

            An entity that a policy is attached to, identified by its ARN.

            • arn (string) --

              The ARN of the entity that the policy is attached to. The ARN format depends on the policy type:

              • For identity, session, and permissions boundary policies, this is the principal ARN (for example, an IAM role or user ARN).

              • For resource-based policies, this is the resource ARN.

              • For organization control policies (SCPs and RCPs), this is the AWS Organizations ARN of the account, organizational unit, or root.

        • policySource (dict) --

          What the policy was built from, such as a KMS key policy or grant. Absent for other policies.

          The type and typeName keys are always present. type identifies the policy-source kind. typeName is its readable name. Compare type, not typeName.

          A policy source can include additional keys that depend on its type. For example, a KMS grant includes a grantId key that identifies the grant. A grant has no ARN. Use the grant ID with the KMS key ARN in attachedTo to find the grant with the AWS KMS ListGrants operation.

          New types and keys can be added, so clients should ignore types and keys they don't recognize.

          • (string) --

            • (string) --

    • nextToken (string) --

      The pagination token for retrieving the next page of evaluations. This value is absent when there are no more results.