---
title: "POST /test-authorization"
method: POST
path: "/test-authorization"
---

# POST /test-authorization

`POST /test-authorization`

Tests if a specified principal is authorized to perform an IoT action on a specified resource. Use this to test and debug the authorization behavior of devices that connect to the IoT device gateway.

Requires permission to access the [TestAuthorization](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-actions-as-permissions) action.

## Query parameters

- `clientId` string

## Request body

- object
  - `principal` string — The principal. Valid principals are CertificateArn (arn:aws:iot:<i>region</i>:<i>accountId</i>:cert/<i>certificateId</i>), thingGroupArn (arn:aws:iot:<i>region</i>:<i>accountId</i>:thinggroup/<i>groupName</i>) and CognitoId (<i>region</i>:<i>id</i>).
  - `cognitoIdentityPoolId` string — The Cognito identity pool ID.
  - `authInfos` AuthInfo[], required — A list of authorization info objects. Simulating authorization will create a response for each <code>authInfo</code> object in the list.
    - `actionType` 'PUBLISH' | 'SUBSCRIBE' | 'RECEIVE' | 'CONNECT' — The type of action for which the principal is being authorized.
    - `resources` Resource[], required — The resources for which the principal is being authorized to perform the specified action.
  - `policyNamesToAdd` PolicyName[] — When testing custom authorization, the policies specified here are treated as if they are attached to the principal being authorized.
  - `policyNamesToSkip` PolicyName[] — When testing custom authorization, the policies specified here are treated as if they are not attached to the principal being authorized.

## Response `200`

Success

- TestAuthorizationResponse
  - `authResults` AuthResult[] — The authentication results.
    - `authInfo` object — Authorization information.
      - `actionType` 'PUBLISH' | 'SUBSCRIBE' | 'RECEIVE' | 'CONNECT' — The type of action for which the principal is being authorized.
      - `resources` Resource[], required — The resources for which the principal is being authorized to perform the specified action.
    - `allowed` object — The policies and statements that allowed the specified action.
      - `policies` Policy[] — A list of policies that allowed the authentication.
        - `policyName` string — The policy name.
        - `policyArn` string — The policy ARN.
    - `denied` object — The policies and statements that denied the specified action.
      - `implicitDeny` object — Information that implicitly denies the authorization. When a policy doesn't explicitly deny or allow an action on a resource it is considered an implicit deny.
        - `policies` Policy[] — Policies that don't contain a matching allow or deny statement for the specified action on the specified resource.
          - `policyName` string — The policy name.
          - `policyArn` string — The policy ARN.
      - `explicitDeny` object — Information that explicitly denies the authorization.
        - `policies` Policy[] — The policies that denied the authorization.
          - `policyName` string — The policy name.
          - `policyArn` string — The policy ARN.
    - `authDecision` 'ALLOWED' | 'EXPLICIT_DENY' | 'IMPLICIT_DENY' — The final authorization decision of this scenario. Multiple statements are taken into account when determining the authorization decision. An explicit deny statement can override multiple allow statements.
    - `missingContextValues` MissingContextValue[] — Contains any missing context values found while evaluating policy.

## Other responses

- `480` — ResourceNotFoundException
- `481` — InvalidRequestException
- `482` — ThrottlingException
- `483` — UnauthorizedException
- `484` — ServiceUnavailableException
- `485` — InternalFailureException
- `486` — LimitExceededException

---

[API](https://skmtc.net/aws/apis/iot.md) · [All operations](https://skmtc.net/aws/apis/iot/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/iot/revisions/deef5c4b09f0/schema)