Role API
An Alexa Smart Properties for healthcare user must have an assigned role before they can access any Alexa Smart Properties for healthcare 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 for Alexa Smart Properties for Healthcare.
API endpoint
The endpoint of the Role API is https://api.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
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 | Residential | Senior Living | Core |
---|---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, CA |
US, UK, FR, CA, IT, DE |
US |
Request format
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 |
---|---|---|---|
|
The unit ID, in the format |
String |
You must specify either a |
|
The ID for the target entity. |
String |
You must specify either a |
|
Role name filter in case the client is interested in the details of a particular role. |
String |
No |
|
Continuation token returned in the response object of the previous list-roles response. |
String |
No |
|
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 |
---|---|---|
|
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
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 |
---|---|---|
|
The role ID. |
String |
|
The role name. |
String |
|
The ID for the unit. |
String |
|
The ID for the target entity. |
String |
|
Token that you can use in the next request as the continuation token ( |
String |
Error response
{
"description": string
}
Error response parameters
Field | Description | Type |
---|---|---|
|
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 that you'll need for the principal, see Obtain Customer Profile Information.
This operation is available in the following countries.
Healthcare | Hospitality | Residential | Senior Living | Core |
---|---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, CA |
US, UK, FR, CA, IT, DE |
US |
Request format
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
}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
|
ID of the role to assign, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request body parameters
Field | Description | Type | Required |
---|---|---|---|
|
User ID of the principal to whom to assign the role. |
String |
Yes |
|
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 |
Response header
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type |
---|---|---|
|
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 |
---|---|---|
|
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. |
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 | Residential | Senior Living | Core |
---|---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, CA |
US, UK, FR, CA, IT, DE |
US |
Request format
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 |
---|---|---|---|
|
The role ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Response header
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field | Description | Type |
---|---|---|
|
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
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 |
---|---|---|
|
The role ID. |
String |
|
The role name. |
String |
|
The unit ID for the unit against which the role is defined. |
String |
|
The ID for the target entity against which the role is defined. |
String |
Error response
{
"description": string
}
Error response parameters
Field | Description | Type |
---|---|---|
|
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 | Residential | Senior Living | Core |
---|---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, CA |
US, UK, FR, CA, IT, DE |
US |
Request format
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 path parameters
Field | Description | Type | Required |
---|---|---|---|
|
The role ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request query parameters
Field | Description | Type | Required |
---|---|---|---|
|
Principal ID, in the format |
String |
Yes |
|
Unit ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
|
Target entity ID. |
String |
Yes |
|
Token used for getting the next page of results. |
String |
No |
|
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 |
---|---|---|
|
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.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
"principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A"
}
],
"paginationContext": {
"nextToken": null
}
}
Response body parameters
Field | Description | Type |
---|---|---|
|
List of results (role assignments). |
List |
|
Role ID. |
String |
|
Principal ID. |
String |
|
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 |
|
Token that you can use in the next request as the continuation token ( |
String |
Error response
{
"description": string
}
Error response parameters
Field | Description | Type |
---|---|---|
|
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 | Residential | Senior Living | Core |
---|---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, CA |
US, UK, FR, CA, IT, DE |
US |
Request format
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 |
---|---|---|---|
|
Role ID, in the Amazon Common Identifier (ACI) format |
String |
Yes |
Request query parameters
Field | Description | Type | Required |
---|---|---|---|
|
Token used for getting the next page of results. |
String |
No |
|
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 |
---|---|---|
|
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.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
"principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A"
}
],
"paginationContext": {
"nextToken": null
}
}
Response body parameters
Field | Description | Type |
---|---|---|
|
List of results (role assignments). |
List |
|
Role ID. |
String |
|
Principal ID. |
String |
|
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 |
|
Token that you can use in the next request as the continuation token ( |
String |
Error response
{
"description": string
}
Error response parameters
Field | Description | Type |
---|---|---|
|
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 | Residential | Senior Living | Core |
---|---|---|---|---|
US |
US, UK, FR, CA, IT, DE |
US, CA |
US, UK, FR, CA, IT, DE |
US |
Request format
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 |
---|---|---|---|
|
Role ID for the role to be revoked. |
String |
Yes |
Request query parameters
Field | Description | Type | Required |
---|---|---|---|
|
Principal ID for the principal whose role is to be revoked. |
String |
Yes |
|
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 |
---|---|---|
|
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 |
---|---|---|
|
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:
|
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. |
Last updated: Mar 30, 2022