Role API

Note: Sign in to the developer console to build or publish your skill.

Note: This API is only available to registered Alexa Smart Properties partners. See Get Started with Alexa Smart Properties APIs.

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

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Note: For unit-based roles, the response contains the same value in both the unitId and targetEntityId fields. For target-entity-based roles, the response contains the targetEntityId field, and the unitId field is null or empty.

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

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

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

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

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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.

Note: This operation can't downgrade a propagated role assignment. If there's an existing role assignment for a given roleId and principalId with propagate set to true, you get an error if you try to make a role assignment request for the same roleId and principalId with a propagation value of false. To downgrade a propagated role assignment, you must first revoke the role assignment with Revoke a role assignment or Batch revoke a role assignment, and then reassign it.

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

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Note: In the response header, the returned Host value is the same as the Host value in the request.

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.

Note: This operation can neither revoke a propagated role assignment without the propagate flag nor revoke a non-propagated role assignment with a propagate flag. That is, if there's an existing role assignment for a given roleId and principalId, you get an error if you try to make a role assignment request for the same roleId and principalId with the opposite propagate value.

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

Note: In the response header, the returned Host value is the same as the Host value in the request.

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?

Provide feedback

Last updated: May 16, 2024