Role API


An Alexa Smart Properties user must have an assigned role before they can access any Alexa Smart Properties resources. The creator of a unit is assigned the administrator role for that unit automatically.

For more details about organizational roles, see About Managing Roles in Alexa Smart Properties.

API endpoint

In the request header, set Host to one of the following, depending on the region of your organization:

Country Endpoint

CA, US

https://api.amazonalexa.com

DE, ES, FR, IT, UK

https://api.eu.amazonalexa.com

JP

https://api.fe.amazonalexa.com

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Role API includes the following operations.

Operation HTTP Method and URI

List roles

GET /v1/roles?unitId={unitId}&roleName={roleName}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken}

Assign a role

POST /v1/roles/{roleId}/assignments

Batch assign a role

POST /v1/roles/{roleId}/assignments/batchAssign

Get a role

GET /v1/roles/{roleId}

List role assignments for a principal

GET /v1/roles/assignments?principalId={principalId}&unitId={unitId}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken}

List principal assignments for a role

GET /v1/roles/{roleId}/assignments?maxResults={maxResults}&nextToken={nextToken}

Revoke a role assignment

DELETE /v1/roles/{roleId}/assignments

Batch revoke a role assignment

POST /v1/roles/{roleId}/assignments/batchRevoke

List roles

Call GET /v1/roles?unitId={unitId}&roleName={roleName}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken} to get the list of roles defined for the specified unit or target entity that can be assigned to a user.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

GET /v1/roles?unitId={unitId}&roleName={roleName}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body

None.

Request query parameters

Field Description Type Required

unitId

The unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

You must specify either a unitId or a targetEntityId.

targetEntityId

The ID for the target entity.

String

You must specify either a unitId or a targetEntityId.

roleName

Role name filter in case the client is interested in the details of a particular role.

String

No

nextToken

Continuation token returned in the response object of the previous list-roles response.

String

No

maxResults

Maximum number of results to display. The value of this parameter must be between 1 and 10. The default value is 10.

Integer

No

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Response body example

{
   "results": [
      {
         "roleId": "amzn1.alexa.role.did.example",
         "roleName": "{roleName}",
         "unitId": "amzn1.alexa.unit.did.example",
         "targetEntityId": "example-target-entity-id"         
      }
   ],
   "paginationContext": {
      "nextToken": null
   }
}

Response body parameters

Field Description Type

roleId

The role ID.

String

roleName

The role name.

String

unitId

The ID for the unit.

String

targetEntityId

The ID for the target entity.

String

paginationContext.nextToken

Token that you can use in the next request as the continuation token (nextToken query parameter) to get the next page of results.

String

Error response

{
    "description": string
}

Error response parameters

Field Description Type

description

A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token."

String

HTTP response codes

Status Code Name Description

200

OK

The request succeeded.

400

Bad Request

The request is malformed or is missing one or more required parameters.

401

Unauthorized

The access token is missing, expired, or invalid.

403

Forbidden

The user doesn't have permission to perform the operation.

404

Not found

The requested roles weren't found.

429

Too many requests

The request is throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

503

Service Unavailable

The server is temporarily unavailable.

Assign a role

Call POST /v1/roles/{roleId}/assignments to assign a role to the specified principal. This API throws a 400 Bad Request Exception if you attempt to assign a role to a principal who is already assigned that particular role. For details about how to retrieve the user ID for the principal, see Obtain Customer Profile Information.

To assign a role temporarily, set the expiresAt property in the request body.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

POST /v1/roles/{roleId}/assignments HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body example

{
   "principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A",
   "propagate" : true,
   "expiresAt": "2021-11-02T12:51:00.000Z"
}

Request path parameters

Field Description Type Required

roleId

ID of the role to assign, in the Amazon Common Identifier (ACI) format "amzn1.alexa.role.did.{id}".

String

Yes

Request body parameters

Field Description Type Required

principalId

User ID of the principal to whom to assign the role.

String

Yes

propagate

Flag that indicates if propagation should be enabled. Propagation assigns the role to the entire unit hierarchy. Only the Amazon Business account's principal ID can propagate roles.

Boolean

No

expiresAt

Assign the role to the specified principal until the specified date and time. Provide the date/time as a UTC timestamp in ISO-8601 format (yyyy-MM-ddTHH:mm:ss[.mmm]Z). The expiration time must be at least 30 minutes after the current time and no more than 30 days from the current time. When not set, the role assignment never expires.


When expiresAt has a value and propagate is true, all assignments in the unit hierarchy inherit the expiration time.

String

No

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Response body

None.

Error response

{
    "description": string
}

Error response parameters

Field Description Type

description

A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token."

String

HTTP response codes

Status Code Name Description

202

Accepted

The role assignment propagation request for the principal is accepted.

204

No content

The request succeeded. This response code only occurs if the request didn't set the propagation flag.

400

Bad Request

The request is malformed or is missing one or more required parameters.

401

Unauthorized

The access token is missing, expired, or invalid.

403

Forbidden

The user doesn't have permission to perform the operation.

404

Not found

The requested roles weren't found.

429

Too many requests

The request is throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

503

Service Unavailable

The server is temporarily unavailable.

Batch assign a role

Call POST /v1/roles/{roleId}/assignments/batchAssign to assign a role to the specified principals. For details about how to retrieve the user IDs for the principals, see Obtain Customer Profile Information.

After accepting the request, this operation performs synchronous validations and then returns a 202 (Accepted) response. Each principal is then assigned to the role asynchronously in the background.

In the case of invalid inputs, the entire batch operation fails. That is, either all the request items are processed or none.

If there's an existing role assignment for a given roleId and principalId with propagate set to false, a role assignment request for the same roleId and principalId with a propagation value of true updates the existing role assignment with propagation.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, JP

US, CA, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

POST /v1/roles/{roleId}/assignments/batchAssign
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body example

{
   "items": [
     {
        "itemId" : 0,
        "principalId": "amzn1.alexa.user.example1",
        "propagate": false,
        "expiresAt": "2021-11-02T12:51:00.000Z"
     },
     {
        "itemId" : 1,         
        "principalId": "amzn1.alexa.user.example2",
        "propagate": true
     },
     {
        "itemId" : 2,
        "principalId": "amzn1.alexa.user.example3",
        "propagate": false
     }
   ]
}

Request path parameters

Field Description Type Required

roleId

ID of the role to assign, in the Amazon Common Identifier (ACI) format "amzn1.alexa.role.did.{id}".

String

Yes

Request body parameters

Field Description Type Required

items

Array of assign role request objects. The maximum number of request items in the batch request is 50.

Array

Yes

items[*].itemId

Unique identifier for the request item.

Integer

Yes

items[*].principalId

User ID of the principal to whom to assign the role.

String

Yes

items[*].propagate

Flag that indicates if propagation should be enabled. Propagation assigns the role to the entire unit hierarchy. Only the Amazon Business account's principal ID can propagate roles. Default: false.

Boolean

No

items[*].expiresAt

Assign the role to the specified principal until the specified date and time. Provide the date/time as a UTC timestamp in ISO-8601 format (yyyy-MM-ddTHH:mm:ss[.mmm]Z). The expiration time must be at least 30 minutes after the current time and no more than 30 days from the current time. When not set, the role assignment never expires.


When expiresAt has a value and propagate is true, all assignments in the unit hierarchy inherit the expiration time.

String

No

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Response body

A successful response has no body.

Error response body example

{
  "errors": [
    {
       "itemId": 0,
       "status": 400,   
       "errorCode" : "INVALID_PRINCIPAL_ID",   
       "errorDescription": "Invalid principalId specified."
    },
    {
       "itemId": 1,
       "status": 400,      
       "errorCode" : "REQUEST_LIMIT_EXCEEDED",
       "errorDescription": "The number of request items in the batch request exceeds the limit (50)."
    }
  ]
}

Error response parameters

Field Description Type

errors

Array of objects that contains descriptions of errors. For a list of possible error codes, see HTTP response codes.

Array

errors[*].itemId

Unique identifier for the request item.

Integer

errors[*].status

Error status. Example: 400.

String

errors[*].errorCode

Error code. Example: INVALID_PRINCIPAL_ID

String

errors[*].errorDescription

A description of the error. Example: Invalid principalId specified.

String

HTTP response codes

Status Code Name Description

202

ACCEPTED

The request to assign a role for the list of principals is accepted.

400

INVALID_PRINCIPAL_ID

Invalid principalId.

400

NO_UNIT_FOR_ROLE

Role is not backed by a unit; propagation isn't supported.

400

ROLE_ASSIGNMENT_NOT_SUPPORTED

Downgrading an already propagated role assignment to a standalone assignment is not supported; the propagate flag should be true.

400

DUPLICATE_REQUEST_ITEM_FOUND

The request contains a duplicate request item.

400

BAD_REQUEST

The request is malformed or is missing any required parameters.

400

INVALID_ROLE_ID

Invalid roleId.

400

REQUEST_LIMIT_EXCEEDED

The request exceeded the limit on the number of principals for role assignment per one request.

401

UNAUTHORIZED

The access token is missing, expired, or invalid.

403

FORBIDDEN

The user doesn't have permission to perform the operation.

404

ROLE_NOT_FOUND

The requested roles weren't found.

429

TOO_MANY_REQUESTS

The request is throttled.

500

INTERNAL_SERVER_ERROR

The request couldn't be handled because of an internal service error.

503

SERVICE_UNAVAILABLE

The server is temporarily unavailable.

Get a role

Call GET /v1/roles/{roleId} to get the details for the specified role.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

GET /v1/roles/{roleId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required

roleId

The role ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.role.did.{id}". Use this ID to assign the role to users.

String

Yes

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Response body example

{
   "roleId": "amzn1.alexa.role.did.example",
   "roleName": "Admin",
   "unitId": "amzn1.alexa.unit.did.example",
   "targetEntityId": "example-target-entity-id"
}

Response body parameters

Field Description Type

roleId

The role ID.

String

roleName

The role name.

String

unitId

The unit ID for the unit against which the role is defined.

String

targetEntityId

The ID for the target entity against which the role is defined.

String

Error response

{
    "description": string
}

Error response parameters

Field Description Type

description

A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token."

String

HTTP response codes

Status Code Name Description

201

OK

The request succeeded.

400

Bad Request

The request is malformed or is missing one or more required parameters.

401

Unauthorized

The access token is missing, expired, or invalid.

403

Forbidden

The user doesn't have permission to perform the operation.

429

Too many requests

The request is throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

503

Service Unavailable

The server is temporarily unavailable.

List role assignments for a principal

Call GET /v1/roles/assignments?principalId={principalId}&unitId={unitId}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken} to get the list of role assignments for the specified principal for the specified unit or target entity.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

GET /v1/roles/assignments?principalId={principalId}&unitId={unitId}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken}  HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request query parameters

Field Description Type Required

principalId

Principal ID, in the format "amzn1.account.{id}". For details on how to retrieve the principal ID, see Obtain Customer Profile Information. The user_id you receive in the customer profile response payload is the value to use for principalId.

String

Yes

unitId

Unit ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.unit.did.{id}".

String

Yes

targetEntityId

Target entity ID.

String

Yes

nextToken

Token used for getting the next page of results.

String

No

maxResults

Maximum number of results to display. The value of this parameter must between 1 and 10. Default is 10.

Integer

No

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Response body example

{
  "results" : [
    {
      "roleId" : "amzn1.alexa.role.did.1",
      "principalId" : "amzn1.account.1",
      "expiresAt": "1715786400000",
      "propagatedRoleId": "amzn1.alexa.role.a4h.originRoleId"
    }
  ],
    "paginationContext": {
      "nextToken": null
  }
}

Response body parameters

Field Description Type

results

List of results (role assignments).

List

results[i].roleId

Role ID.

String

results[i].principalId

Principal ID.

String

results[i].expiresAt

The timestamp in epoch time format (1715786400000) at which the assigned role for the principal expires. Included when expiresAt was set when assigning the role.

String

results[i].propagatedRoleId

The roleId of the origin role from which this role assignment is propagated from.

String

paginationContext

Object containing pagination information. If present, the response contains incomplete results. If omitted, all results were already returned. For details, see Handling Pagination in Query Results.

Object

paginationContext.nextToken

Token that you can use in the next request as the continuation token (nextToken query parameter) to get the next page of results.

String

Error response

{
    "description": string
}

Error response parameters

Field Description Type

description

A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token."

String

HTTP response codes

Status Code Name Description

200

OK

The request succeeded.

400

Bad Request

The request is malformed or is missing one or more required parameters.

401

Unauthorized

The access token is missing, expired, or invalid.

403

Forbidden

The user doesn't have permission to perform the operation.

429

Too many requests

The request is throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

503

Service Unavailable

The server is temporarily unavailable.

List principal assignments for a role

Call GET /v1/roles/{roleId}/assignments?maxResults={maxResults}&nextToken={nextToken} to get the list of principal assignments for the specified role.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

GET /v1/roles/{roleId}/assignments?maxResults={maxResults}&nextToken={nextToken} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Field Description Type Required

roleId

Role ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.role.did.{id}".

String

Yes

Request query parameters

Field Description Type Required

nextToken

Token used for getting the next page of results.

String

No

maxResults

Maximum number of results to display. The value of this parameter must between 1 and 10. Default is 10.

Integer

No

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Response body example

{
  "results": [
    {
      "roleId": "amzn1.alexa.role.did.1",
      "principalId": "amzn1.account.1",
      "expiresAt": "1715786400000",
      "propagatedRoleId": "amzn1.alexa.role.a4h.originRoleId"
    }
  ],
  "paginationContext": {
    "nextToken": null
  }
}

Response body parameters

Field Description Type

results

List of results (role assignments).

List

results[i].roleId

Role ID.

String

results[i].principalId

Principal ID.

String

results[i].expiresAt

The timestamp in epoch time format (1715786400000) at which the assigned role for the principal expires. Included when expiresAt was set when assigning the role.

String

results[i].propagatedRoleId

The roleId of the origin role from which this role assignment is propagated from.

String

paginationContext

Object containing pagination information. If present, the response contains incomplete results. If omitted, all results were already returned. For details, see Handling Pagination in Query Results.

Object

paginationContext.nextToken

Token that you can use in the next request as the continuation token (nextToken query parameter) to get the next page of results.

String

Error response

{
    "description": string
}

Error response parameters

Field Description Type

description

A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token."

String

HTTP response codes

Status Code Name Description

200

OK

The request succeeded.

400

Bad Request

The request is malformed or is missing one or more required parameters.

401

Unauthorized

The access token is missing, expired, or invalid.

403

Forbidden

The user doesn't have permission to perform the operation.

404

Not found

The requested roles weren't found.

429

Too many requests

The request is throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

503

Service Unavailable

The server is temporarily unavailable.

Revoke a role assignment

Call DELETE /v1/roles/{roleId}/assignments to revoke a role for the specified principal.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, IT, DE, ES, JP

US, UK, FR, CA, IT, DE, ES, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

DELETE /v1/roles/{roleId}/assignments HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request and response example

DELETE /v1/roles/amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ/assignments?principalId=amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2Ax&propagate=false

204 No Content

Request body

None.

Request path parameters

Field Description Type Required

roleId

Role ID for the role to be revoked.

String

Yes

Request query parameters

Field Description Type Required

principalId

Principal ID for the principal whose role is to be revoked.

String

Yes

propagate

Query parameter flag that indicates if propagation should be enabled. Propagation revokes the role from the entire unit hierarchy. Only the Amazon Business account's principal ID can propagate roles.

Boolean

No

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Response body

None.

Error response

{
    "description": string
}

Error response parameters

Field Description Type

description

A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token."

String

HTTP response codes

Status Code Name Description

202

Accepted

Role revocation propagation request for the principal is accepted.

204

No content

Role revoked for principal. This response code only occurs if the revocation request didn't set the propagation flag.

400

Bad Request

The request is malformed or is missing one or more required parameters. Example reasons include:
  • You attempted to revoke a role assignment that's propagated from a different unit.
  • You attempted to revoke a propagated role assignment without the propagate flag (or vice versa).

401

Unauthorized

The access token is missing, expired, or invalid.

403

Forbidden

The user doesn't have permission to perform the operation.

404

Not found

The requested roles weren't found.

429

Too many requests

The request is throttled.

500

Internal Server Error

The request couldn't be handled because of an internal service error.

503

Service Unavailable

The server is temporarily unavailable.

Batch revoke a role assignment

Call POST /v1/roles/{roleId}/assignments/batchRevoke to revoke a role for the specified principals. For details about how to retrieve the user IDs that you need for the principals, see Obtain Customer Profile Information.

After accepting the request, this operation performs perform synchronous validations and then returns a 202 (Accepted) response. Each principal is then revoked for the role asynchronously in the background.

In the case of invalid inputs, the entire batch operation fails. That is, either all the request items are processed or none.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

US

US, UK, FR, CA, JP

US, CA, JP

US

Request format

In the request header, set Host to the appropriate endpoint for the region of your organization. See API endpoint, earlier.

POST /v1/roles/{roleId}/assignments/batchRevoke
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request body example

{
   "items": [
     {
        "itemId" : 0,
        "principalId": "amzn1.alexa.user.example1",
        "propagate": false
     },
     {
        "itemId" : 1,         
        "principalId": "amzn1.alexa.user.example2",
        "propagate": true
     },
     {
        "itemId" : 2,
        "principalId": "amzn1.alexa.user.example3",
        "propagate": false
     }
   ]
}

Request path parameters

Field Description Type Required

roleId

ID of the role to revoke, in the Amazon Common Identifier (ACI) format "amzn1.alexa.role.did.{id}".

String

Yes

Request body parameters

Field Description Type Required

items

Array of assign role request objects. The maximum number of request items in the batch request is 50.

Array

Yes

items[*].itemId

Unique identifier for the request item.

Integer

Yes

items[*].principalId

User ID of the principal to whom to assign the role.

String

Yes

items[*].propagate

Flag that indicates if propagation should be enabled. Propagation assigns the role to the entire unit hierarchy. Only the Amazon Business account's principal ID can propagate roles. The value of this flag must match the value of the associated flag for a given roleId and principalId role assignment, or you will encounter an error.
Default: false.

Boolean

No

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Response body

A successful response has no body.

Error response body example

{
  "errors": [
    {
       "itemId": 0,
       "status": 400,   
       "errorCode" : "INVALID_PRINCIPAL_ID",   
       "errorDescription": "Invalid principalId specified."
    },
    {
       "itemId": 1,
       "status": 400,      
       "errorCode" : "REQUEST_LIMIT_EXCEEDED",
       "errorDescription": "The number of request items in the batch request exceeds the limit (50)."
    }
  ]
}

Error response parameters

Field Description Type

errors

Array of objects that contains descriptions of errors. For a list of possible error codes, see HTTP response codes.

Array

errors[*].itemId

Unique identifier for the request item.

Integer

errors[*].status

Error status. Example: 400.

String

errors[*].errorCode

Error code. Example: INVALID_PRINCIPAL_ID

String

errors[*].errorDescription

A description of the error. Example: Invalid principalId specified.

String

HTTP response codes

Status Code Name Description

202

ACCEPTED

The request to revoke a role assignment for the list of principals is accepted.

400

INVALID_PRINCIPAL_ID

Invalid principalId.

400

PROPAGATED_FROM_ANOTHER_ROLE

You attempted to revoke a propagated role assignment. Reinitiate revoke propagation at the source with the propagate flag set to true.

400

PRINCIPAL_IS_PROPAGATED

The role revocation isn't supported for the principal. The current role assignment is the source of a propagation chain. You must pass in the propagate flag with a value of true.

400

PRINCIPAL_IS_NOT_PROPAGATED

The role revocation isn't supported for the principal. The current role assignment is a non-propagated assignment. Either don't pass in the propagate flag, or set the propagate flag to false.

400

DUPLICATE_REQUEST_ITEM_FOUND

The request contains a duplicate request item.

400

BAD_REQUEST

The request is malformed or is missing any required parameters.

400

INVALID_ROLE_ID

Invalid roleId.

400

REQUEST_LIMIT_EXCEEDED

The request exceeded the limit on the number of principals for role assignment per one request.

401

UNAUTHORIZED

The access token is missing, expired, or invalid.

403

FORBIDDEN

The user doesn't have permission to perform the operation.

404

ROLE_NOT_FOUND

The requested roles weren't found.

429

TOO_MANY_REQUESTS

The request is throttled.

500

INTERNAL_SERVER_ERROR

The request couldn't be handled because of an internal service error.

503

SERVICE_UNAVAILABLE

The server is temporarily unavailable.


Was this page helpful?

Last updated: May 16, 2024