Role API

An Alexa for Hospitality user must have an assigned role before they can access any Alexa 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 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

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
   "results": [
      {
         "roleId": "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
         "roleName": "{roleName}",
         "unitId": "amzn1.alexa.unit.did.AEOLAJQBM6PQSO3E4QQEA6WIR56IFW4WWUIGOVZ4CMBG4CGTYG6ULAUMS6NWFWRHBH72PVR4TFSUNQRDLSKN2MHTE3BUU3CGHIVOJ4TZ"
      }
   ],
   "paginationContext": {
      "nextToken": null
   }
}

Response body parameters

Error response

{
    "description": string
}

Error response parameters

HTTP response codes

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

Request body parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body

None.

Error response

{
    "description": string
}

Error response parameters

HTTP response codes

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

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
   "roleId": "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
   "roleName": "Admin",
   "unitId": "amzn1.alexa.unit.did.AEOLAJQBM6PQSO3E4QQEA6WIR56IFW4WWUIGOVZ4CMBG4CGTYG6ULAUMS6NWFWRHBH72PVR4TFSUNQRDLSKN2MHTE3BUU3CGHIVOJ4TZ"
}

Response body parameters

Error response

{
    "description": string
}

Error response parameters

HTTP response codes

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

Request query parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
  "results" : [
    {
      "roleId" : "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
      "principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A"
    }
  ],
    "paginationContext": {
      "nextToken": null
  }
}

Response body parameters

Error response

{
    "description": string
}

Error response parameters

HTTP response codes

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

Request query parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
   "results": [
      {
         "roleId": "amzn1.alexa.role.did.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
         "principalId" : "amzn1.account.AHRZS727KGPWJQGQRPSGZRDDOV2A"
      }
   ],
   "paginationContext": {
      "nextToken": null
   }
}

Response body parameters

Error response

{
    "description": string
}

Error response parameters

HTTP response codes

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

Request query parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body

None.

Error response

{
    "description": string
}

Error response parameters

HTTP response codes