Role API

An Alexa Smart Properties in senior living user must have an assigned role before they can access any Alexa Smart Properties in senior living 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 in Senior Living.

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

X-Amzn-RequestId

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

Token that you can use 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

description

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.

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

X-Amzn-RequestId

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

description

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

204

No content

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.

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

X-Amzn-RequestId

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.AGUUQ4CBCDQUIRJZIZY4V3KMLSICW5MEQ2NR25XL5MQHCEFPYZFBQPDAOGVSMDU2SLO4A4PIDFNBMGX2T2LFLYQLTFLGMDSZIANNOPUJ",
   "roleName": "Admin",
   "unitId": "amzn1.alexa.unit.did.AEOLAJQBM6PQSO3E4QQEA6WIR56IFW4WWUIGOVZ4CMBG4CGTYG6ULAUMS6NWFWRHBH72PVR4TFSUNQRDLSKN2MHTE3BUU3CGHIVOJ4TZ"
}

Response body parameters

Field Description Type

roleId

The role ID.

String

roleName

The role name.

String

unitId

The unit ID for the unit against which the role is defined.

String

Error response

{
    "description": string
}

Error response parameters

Field Description Type

description

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

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

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

X-Amzn-RequestId

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

results

List of results (role assignments).

List

results[i].roleId

Role ID.

String

results[i].principalId

Principal ID.

String

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

paginationContext.nextToken

Token that you can use in the next request as the continuation token (nextToken query parameter) to get the next page of results.

String

Error response

{
    "description": string
}

Error response parameters

Field Description Type

description

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

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

X-Amzn-RequestId

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

results

List of results (role assignments).

List

results[i].roleId

Role ID.

String

results[i].principalId

Principal ID.

String

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

paginationContext.nextToken

Token that you can use in the next request as the continuation token (nextToken query parameter) to get the next page of results.

String

Error response

{
    "description": string
}

Error response parameters

Field Description Type

description

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.

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

Role ID for the role to be revoked.

String

Yes

Request query parameters

Field Description Type Required

principalId

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

X-Amzn-RequestId

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

description

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

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