Role API

Each Alexa for Residential user must be assigned a role before they can access any Alexa for Residential resources. For more information about organizational roles, see Managing Roles in Alexa for Residential.

List roles

Call GET /v1/roles?unitId={unitId} to get the list of roles defined for the specified unit.

Request format

GET /v1/roles?unitId={unitId} 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}" for which roles are to be fetched. String Yes
roleName Role name filter in case client is interested in the details of a particular role. String Yes
nextToken Continuation token returned in response object of previous list roles response. 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",
         "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

HTTP/1.1 {ErrorCode}
{
    "code": "{ErrorCode}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
code The error code for the error. Integer Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. String No

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 will throw a 400 Bad Request Exception if you attempt to assign a role to a principal who has already been assigned that particular role. See Obtain Customer Profile Information for information about the how to retrieve the user ID that you'll need for the principal.

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

HTTP/1.1 {ErrorCode}
{
    "code": "{ErrorCode}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
code The error code for the error. Integer Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. String No

HTTP response codes

Status Code Name Description
204 No content Setting applied.
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.

List assignments for a role

Call GET /v1/roles/{roleId}/assignments to get the list of assignments for the specified role.

Request format

GET /v1/roles/{roleId}/assignments 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. 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

HTTP/1.1 {ErrorCode}
{
    "code": "{ErrorCode}",
    "message": "{ErrorMessage}"
}

Error response parameters

Field Description Type Required
code The error code for the error. Integer Yes
message The error message for the error. Note that the error message is exposed only for debugging/logging purposes and must not be exposed to the customer. No business logic should depend on the content of the error message. String No

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.