Role API
An Alexa Smart Properties for hospitality user must have an assigned role before they can access any Alexa Smart Properties for hospitality 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 for Hospitality.
List roles
Call GET /v1/roles?unitId={unitId}
to get the list of roles defined for the specified unit that can be assigned to a user.
Note: In the request header, set
Host
to one of the following, depending on the region of your
organization:
api.amazonalexa.com
or
api.eu.amazonalexa.com
.
GET /v1/roles?unitId={unitId}&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 |
Yes |
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 |
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 |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body example
{
"results": [
{
"roleId": "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
"roleName": "{roleName}",
"unitId": "amzn1.alexa.unit.did.AEOLAJQBM6PQSO3E4QQEA6WIR56IFW4WWUIGOVZ4CMBG4CGTYG6ULAUMS6NWFWRHBH72PVR4TFSUNQRDLSKN2MHTE3BUU3CGHIVOJ4TZ"
}
],
"paginationContext": {
"nextToken": null
}
}
Response body parameters
Field |
Description |
Type |
Required |
roleId |
The role ID. |
String |
Yes |
roleName |
The role name. |
String |
Yes |
unitId |
The ID for the unit. |
Integer |
Yes |
paginationContext.nextToken |
Use the value of nextToken in the next request as the continuation token to list the next set of objects. |
String |
No |
Error response
{
"description": string
}
Error response parameters
Field |
Description |
Type |
Required |
description |
A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token." |
String |
Yes |
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 authorization 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 |
Too many requests. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
Service 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.
Note: In the request header, set
Host
to one of the following, depending on the region of your
organization:
api.amazonalexa.com
or
api.eu.amazonalexa.com
.
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"
}
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 |
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 |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body
None.
Error response
{
"description": string
}
Error response parameters
Field |
Description |
Type |
Required |
description |
A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token." |
String |
Yes |
HTTP response codes
Status code |
Name |
Description |
204 |
No content |
The request succeeded. |
400 |
Bad Request |
The request is malformed or is missing one or more required parameters. |
401 |
Unauthorized |
The authorization 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 |
Too many requests. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
Service Unavailable. |
Get a role
Call GET /v1/roles/{roleId}
to get the details for the specified role.
Note: In the request header, set
Host
to one of the following, depending on the region of your
organization:
api.amazonalexa.com
or
api.eu.amazonalexa.com
.
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 |
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 |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body example
{
"roleId": "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
"roleName": "Admin",
"unitId": "amzn1.alexa.unit.did.AEOLAJQBM6PQSO3E4QQEA6WIR56IFW4WWUIGOVZ4CMBG4CGTYG6ULAUMS6NWFWRHBH72PVR4TFSUNQRDLSKN2MHTE3BUU3CGHIVOJ4TZ"
}
Response body parameters
Field |
Description |
Type |
Required |
roleId |
The role ID. |
String |
Yes |
roleName |
The role name. |
String |
Yes |
unitId |
The unit ID for the unit against which the role is defined. |
String |
Yes |
Error response
{
"description": string
}
Error response parameters
Field |
Description |
Type |
Required |
description |
A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token." |
String |
Yes |
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 authorization token is missing, expired, or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
429 |
Too many requests |
Too many requests. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
Service is temporarily unavailable. |
List role assignments for a principal
Call GET /v1/roles/assignments
to get the list of role assignments for the specified principal for the specified unit.
Note: In the request header, set
Host
to one of the following, depending on the region of your
organization:
api.amazonalexa.com
or
api.eu.amazonalexa.com
.
GET /v1/roles/assignments?principalId={principalId}&unitId={unitId}&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 |
The role ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.role.did.{id}" . |
String |
Yes |
Request query parameters
Field |
Description |
Type |
Required |
principalId |
The 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 |
The unit ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.role.did.{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 |
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 |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body example
{
"results" : [
{
"roleId" : "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
"principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A"
}
],
"paginationContext": {
"nextToken": null
}
}
Response body parameters
Field |
Description |
Type |
Required |
results |
List of results (role assignments). |
List |
Yes |
results[i].roleId |
The role ID. |
String |
Yes |
results[i].principalId |
The principal ID. |
String |
Yes |
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 |
No |
paginationContext.nextToken |
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. |
String |
No |
Error response
{
"description": string
}
Error response parameters
Field |
Description |
Type |
Required |
description |
A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token." |
String |
Yes |
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 authorization token is missing, expired, or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
429 |
Too many requests |
Too many requests. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
Service is temporarily unavailable. |
List principal assignments for a role
Call GET /v1/roles/{roleId}/assignments
to get the list of principal assignments for the specified role.
Note: In the request header, set
Host
to one of the following, depending on the region of your
organization:
api.amazonalexa.com
or
api.eu.amazonalexa.com
.
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 |
The 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 |
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 |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body example
{
"results": [
{
"roleId": "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
"principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A"
}
],
"paginationContext": {
"nextToken": null
}
}
Response body parameters
Field |
Description |
Type |
Required |
results |
List of results (role assignments). |
List |
Yes |
results[i].roleId |
The role ID. |
String |
Yes |
results[i].principalId |
The principal ID. |
String |
Yes |
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 |
No |
paginationContext.nextToken |
Use the value of nextToken in the next request as the continuation token (nextToken query parameter) to get the next page of results. |
String |
No |
Error response
{
"description": string
}
Error response parameters
Field |
Description |
Type |
Required |
description |
A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token." |
String |
Yes |
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 authorization 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 |
Too many requests. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
Service is temporarily unavailable. |
Revoke a role assignment
Call DELETE /v1/roles/{roleId}/assignments
to revoke a role for the specified principal.
Note: In the request header, set
Host
to one of the following, depending on the region of your
organization:
api.amazonalexa.com
or
api.eu.amazonalexa.com
.
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
204 No Content
Request body
None.
Request path parameters
Field |
Description |
Type |
Required |
roleId |
The role ID for the role to be revoked. |
String |
Yes |
Request query parameters
Field |
Description |
Type |
Required |
principalId |
The principal ID for the principal whose role is to be revoked. |
String |
Yes |
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 |
Required |
X-Amzn-RequestId |
Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem. |
String |
Yes |
Response body
None.
Error response
{
"description": string
}
Error response parameters
Field |
Description |
Type |
Required |
description |
A description of the error, for example "HTTP/1.1 401 The request has a missing or an invalid access token." |
String |
Yes |
HTTP response codes
Status code |
Name |
Description |
204 |
No content |
Role revoked for principal. |
400 |
Bad Request |
The request is malformed or is missing one or more required parameters. |
401 |
Unauthorized |
The authorization token is missing, expired, or invalid. |
403 |
Forbidden |
The user doesn't have permission to perform the operation. |
404 |
Not found |
The requested resource wasn't found. |
429 |
Too many requests |
Too many requests. |
500 |
Internal Server Error |
The request couldn't be handled because of an internal service error. |
503 |
Service Unavailable |
Service Unavailable. |