Role API

An Alexa Smart Properties for healthcare user must have an assigned role before they can access any Alexa Smart Properties for healthcare 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 for Alexa Smart Properties for Healthcare.

API endpoint

The endpoint of the Role API is https://api.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA).

Operations

The Role API includes the following operations.

Operation HTTP Method and URI

List roles

GET /v1/roles?unitId={unitId}

Assign a role

POST /v1/roles/{roleId}/assignments

Get a role

GET /v1/roles/{roleId}

List role assignments for a principal

GET /v1/roles/assignments

List principal assignments for a role

GET /v1/roles/{roleId}/assignments

Revoke a role assignment

DELETE /v1/roles/{roleId}/assignments

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",
   "propagate" : true
}

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

propagate

Flag that indicates if propagation should be enabled. Propagation assigns the role to the entire unit hierarchy. Only the Amazon Business account's principal ID can propagate roles.

Boolean

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

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

202

Accepted

The role assignment propagation request for the principal is accepted.

204

No content

The request succeeded. This response code only occurs if the request didn't set the propagation flag.

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&propagate=false

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

propagate

Query parameter flag that indicates if propagation should be enabled. Propagation revokes the role from the entire unit hierarchy. Only the Amazon Business account's principal ID can propagate roles.

Boolean

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

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

202

Accepted

Role revocation propagation request for the principal is accepted.

204

No content

Role revoked for principal. This response code only occurs if the revocation request didn't set the propagation flag.

400

Bad Request

The request is malformed or is missing one or more required parameters. Example reasons include:
  • You attempted to revoke a role assignment that's propagated from a different unit.
  • You attempted to revoke a propagated role assignment without the propagate flag (or vice versa).

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.