Role REST API Reference
Use the Role REST API to manage organizational roles in Alexa Smart Properties (ASP). A role defines the operations that the user has permission to perform on units. Before a user can access any ASP resources, the user must have an assigned role. Alexa assigns the administrator role to the creator of a unit automatically.
For more details about organizational roles, see About Managing Roles in Alexa Smart Properties.
API endpoint
Based on the country of your organization, set the Host parameter in the request header to one of the following API endpoints.
| Country | Endpoint |
|---|---|
|
CA, US |
|
|
DE, ES, FR, IT, UK |
|
|
JP |
|
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.
Operations
The Role API includes the following operations.
| Operation | HTTP Method and URI |
|---|---|
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
|
Assign role
Assign the specified role to the specified principal. You can't assign the same role to a principal who is already assigned that role. For details about how to retrieve the user ID for the principal, see Obtain Customer Profile Information. You can assign a role and optionally propagate the role assignment to the property hierarchy. And, you can assign a role temporarily.
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
To assign a role, you make a POST request to the POST /v1/roles/{roleId}/assignments resource.
Request path and header example
POST /v1/roles/{roleId}/assignments HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the role. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
"principalId" : "amzn1.account.1",
"propagate" : true,
"expiresAt": "2021-11-02T12:51:00.000Z"
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
Identifies the principal for whom to assign the role. |
String |
Yes |
|
|
Indicates whether to propagate the role assignment to the entire unit hierarchy. |
Boolean |
No |
|
|
Assign the role to the specified principal until the specified expiration date and time. |
String |
No |
Response
A successful response returns HTTP 202 Accepted or HTTP 204 No content.
On error, the response returns the appropriate HTTP status code and includes a response body with a human-readable description.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Role assigned successfully and the propagation request for the specified principal accepted. |
|
|
Role assigned successfully. No propagation specified. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Batch assign role
Assign the specified role to the list of principals. For details about how to retrieve the user ID for the principal, see Obtain Customer Profile Information. You can assign a role and optionally propagate the role assignment to the property hierarchy. And, you can assign a role temporarily.
After accepting the request, this operation performs synchronous validations and then returns a successful response. Each principal is then assigned to the role asynchronously in the background. For any inputs that aren't valid, the entire operation fails. Either all the request items are processed or none are processed.
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.
roleId and principalId with propagate set to true, the operation returns 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
To assign a role, you make a POST request to the POST /v1/roles/{roleId}/assignments/batchAssign resource.
Request path and header example
POST /v1/roles/{roleId}/assignments/batchAssign HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the role. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"items": [
{
"itemId" : 0,
"principalId": "amzn1.alexa.user.2",
"propagate": false,
"expiresAt": "2021-11-02T12:51:00.000Z"
},
{
"itemId" : 1,
"principalId": "amzn1.alexa.user.3",
"propagate": true
},
{
"itemId" : 2,
"principalId": "amzn1.alexa.user.4",
"propagate": false
}
]
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
List of principals to which to assign the role. |
Array of objects |
Yes |
|
|
Unique identifier for the assignment. |
Integer |
Yes |
|
|
Identifies the principal for whom to assign the role. |
String |
Yes |
|
|
Indicates whether to propagate the role assignment to the entire unit hierarchy. |
Boolean |
No |
|
|
Assign the role to the specified principal until the specified expiration date and time. |
String |
No |
Response
A successful response returns HTTP 202 Accepted.
On error, the response returns the appropriate HTTP status code and includes a response body with a BatchError object.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Request to assign a role for the specified principals accepted. |
|
|
Indicates that one or more properties in the request body aren't valid.
|
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Batch revoke role assignment
Remove a role assignment for the specified list of principals. You can enable propagation to revoke the role assignment to the property hierarchy.
After accepting the request, this operation performs synchronous validations and then returns a successful response. Each principal is then revoked from the role asynchronously in the background. For any inputs that aren't valid, the entire operation fails. Either all the request items are processed or none are processed.
propagate flag with the same value that you used in the assign role operations. You can't revoke a propagated role assignment without propagate=true and you can't revoke a non-propagated role assignment with propagate=false.This operation is available in the following countries.
| Healthcare | Hospitality | Senior Living | Core |
|---|---|---|---|
|
US |
US, UK, FR, CA, JP |
US, CA, JP |
US |
Request
To remove the role, you make a POST request to the /v1/roles/{roleId}/assignments/batchRevoke resource.
Request path and header example
POST /v1/roles/{roleId}/assignments/batchRevoke
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the role. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
{
"items": [
{
"itemId" : 0,
"principalId": "amzn1.alexa.user.example1",
"propagate": false
},
{
"itemId" : 1,
"principalId": "amzn1.alexa.user.3",
"propagate": true
},
{
"itemId" : 2,
"principalId": "amzn1.alexa.user.4",
"propagate": false
}
]
}
Request body properties
| Property | Description | Type | Required |
|---|---|---|---|
|
|
List of principals to which to revoke the role. |
Array of objects |
Yes |
|
|
Unique identifier for the assignment. |
Integer |
Yes |
|
|
Identifies the principal for whom to revoke the role. |
String |
Yes |
|
|
Indicates whether to propagate the role revocation to the entire unit hierarchy. |
Boolean |
No |
Response
A successful response returns HTTP 202 Accepted.
On error, the response returns the appropriate HTTP status code and includes a response body with a BatchError object.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Request to revoke a role for the specified principals accepted. |
|
|
Indicates that one or more properties in the request body aren't valid.
|
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get role
Get the details of 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
To get the role details, you make a GET request to the /v1/roles/{roleId} resource.
Request path and header example
GET /v1/roles/{roleId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the role. |
String |
Yes |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK, along with the details of the role.
On error, the response returns the appropriate HTTP status code and includes a response body with a human-readable description.
Response body example
{
"roleId": "amzn1.alexa.role.did.1",
"roleName": "Admin",
"unitId": "amzn1.alexa.unit.did.101",
"targetEntityId": "target.entity.1"
}
Response body properties
unitId and targetEntityId fields. For target-entity-based roles, the response contains the targetEntityId field, and the unitId field is null or empty.| Property | Description | Type |
|---|---|---|
|
|
Identifies the role for the unit. |
String |
|
|
Name of the role. |
String |
|
|
Identifies the unit assigned the role. |
String |
|
|
Identifies the target entity assigned the role. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains the details of the role. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List principal assignments
List the 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
To list assignments, you make a GET request to the /v1/roles/{roleId}/assignments resource.
Request path and header example
GET /v1/roles/{roleId}/assignments?maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the role. |
String |
Yes |
|
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
|
Query |
Token from the previous response. |
String |
No |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK, along with a list of role assignments.
On error, the response returns the appropriate HTTP status code and includes a response body with a human-readable description.
Response body example
{
"results": [
{
"roleId": "amzn1.alexa.role.did.1",
"principalId": "amzn1.account.1",
"expiresAt": "2021-06-10T14:00:00Z",
"propagatedRoleId": "amzn1.alexa.role.originRoleId"
},
{
"roleId": "amzn1.alexa.role.did.1",
"principalId": "amzn1.account.2",
"expiresAt": "2021-06-10T14:00:00Z",
"propagatedRoleId": "amzn1.alexa.role.originRoleId"
}
],
"paginationContext": {
"nextToken": null
}
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
List of role assignments |
Array of objects |
|
|
Identifies the role. |
String |
|
|
Identifies the principal assigned to the role. |
String |
|
|
(Optional) Expiration date and time at which the assigned role expires. |
String |
|
|
(Optional) Identifies the original role from which this role assignment propagated. |
String |
|
|
Indicates whether there are more results to return. |
Object |
|
|
Included when the response is truncated. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains a list of role assignments. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List roles
Get a list of roles defined for the specified unit or target entity. You can assign these roles to a user by using Assign role or Batch assign 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
To list roles, you make a GET request to the /v1/roles resource.
Request path and header example
GET /v1/roles?unitId={unitId}&targetEntityId={targetEntityId}&roleName={roleName}&maxResults={maxResults}&nextToken={nextToken}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Query |
Filter on the unit. |
String |
No |
|
|
Query |
Filter on the name of the target entity. |
String |
No |
|
|
Query |
Filter on the name of the role. |
String |
No |
|
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
|
Query |
Token from the previous response. |
String |
No |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK, along with a list of roles for the specified unit or target entity.
On error, the response returns the appropriate HTTP status code and includes a response body with a human-readable description.
Response body example
{
"results": [
{
"roleId": "amzn1.alexa.role.did.1",
"roleName": "Admin",
"unitId": "amzn1.alexa.unit.did.101",
"targetEntityId": "amzn1.alexa.unit.did.101"
},
{
"roleId": "amzn1.alexa.role.did.2",
"roleName": "ReadOnly",
"unitId": "amzn1.alexa.unit.did.101",
"targetEntityId": "amzn1.alexa.unit.did.101"
}
],
"paginationContext": {
"nextToken": someToken.1
}
}
Response body properties
unitId and targetEntityId fields. For target-entity-based roles, the response contains the targetEntityId field, and the unitId field is null or empty.| Property | Description | Type |
|---|---|---|
|
|
List of roles for the specified unit or target entity. |
Array of objects |
|
|
Identifies the role for the unit. |
String |
|
|
Name of the role. |
String |
|
|
Identifies the unit assigned the role. |
String |
|
|
Identifies the target entity assigned the role. |
String |
|
|
Indicates whether there are more results to return. |
Object |
|
|
Included when the response is truncated. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains list of roles for the specified unit or target entity. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
List role assignments
List role assignments for the specified principal and 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
To list assignments, you make a GET request to the /v1/roles/assignments resource.
Request path and header example
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 {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Query |
Identifies the principal for whom to get the role assignments. |
String |
Yes |
|
|
Query |
Filter on the unit. |
String |
No |
|
|
Query |
Filter on the name of the target entity. |
String |
No |
|
|
Query |
Maximum number of results to return in the response. |
Integer |
No |
|
|
Query |
Token from the previous response. |
String |
No |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 200 OK, along with a list of role assignments for the specified principal.
On error, the response returns the appropriate HTTP status code and includes a response body with a human-readable description.
Response body example
{
"results" : [
{
"roleId" : "amzn1.alexa.role.did.1",
"principalId" : "amzn1.account.1",
"expiresAt": "2021-06-10T14:00:00Z",
"propagatedRoleId": "amzn1.alexa.role.originRoleId"
}
],
"paginationContext": {
"nextToken": null
}
}
Response body properties
| Property | Description | Type |
|---|---|---|
|
|
List of roles for the specified principal. |
Array of objects |
|
|
Identifies the role assigned to the specified principal. |
String |
|
|
Identifies the principal. |
String |
|
|
(Optional) Expiration date and time at which the assigned role expires. |
String |
|
|
(Optional) Identifies the original role from which this role assignment propagated. |
String |
|
|
Indicates whether there are more results to return. |
Object |
|
|
Included when the response is truncated. |
String |
HTTP status codes
| Status | Description |
|---|---|
|
|
Response body contains a list of role assignments for the specified principal. |
|
|
Indicates that one or more properties in the request body aren't valid. |
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Revoke role assignment
Remove a role assignment for the specified principal. You can enable propagation to revoke the role assignment to the property hierarchy.
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
To remove a role assignment, you make a DELETE request to the /v1/roles/{roleId}/assignments resource.
Request path and header example
DELETE /v1/roles/{roleId}/assignments?principalId={principalId}&propagate={propagate}
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}
Request path and header parameters
| Parameter | Located in | Description | Type | Required |
|---|---|---|---|---|
|
|
Path |
Identifies the role. |
String |
Yes |
|
|
Query |
Identifies the principal for whom to revoke the role assignment. |
String |
Yes |
|
|
Query |
Indicates whether to propagate the role revocation to the entire unit hierarchy. |
Boolean |
No |
|
|
Header |
Access token for the customer. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The request has no body.
Response
A successful response returns HTTP 202 Accepted or HTTP 204 No content.
On error, the response returns the appropriate HTTP status code and includes a response body with a human-readable description.
Response body example
The response has no body.
Response body properties
The response has no body.
HTTP status codes
| Status | Description |
|---|---|
|
|
Role revoked successfully and the propagation request for the specified principal accepted. |
|
|
Role revoked successfully. No propagation specified. |
|
|
Indicates that one or more properties in the request body aren't valid.
|
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
|
Requested resource not found. |
|
|
Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off. |
|
|
Error occurred on the server. You can retry the request by using exponential back-off. |
|
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Object definitions
The Role API defines the following object definitions.
BatchError object
The BatchError object defines the error code and description included in the response when an error occurs during a batch operation.
The following example shows the response body.
{
"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)."
}
]
}
The BatchError object defines the following properties.
| Property | Description | Type |
|---|---|---|
|
|
(Optional) Identifies the request item that failed. |
Integer |
|
|
HTTP status code. |
String |
|
|
Type of error that occurred. |
String |
|
|
Human-readable error message. The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. |
String |
Related topics
Last updated: Dec 04, 2024