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.

Request format

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

Response header

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.

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"
}

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

Response header

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.

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
roleId The role ID, in the Amazon Common Identifier (ACI) format "amzn1.alexa.role.did.{id}". Use this ID to assign the role to users. String Yes

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json
Field Description Type 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.

Request format

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

Response header

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.

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
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

Response header

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.

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

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

Response header

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.