Role API

Note: Submit your skill and see it come to life.

Note: This API is only available to registered Alexa Smart Properties for healthcare partners. See Get Started with Alexa Smart Properties for Healthcare APIs.

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}&roleName={roleName}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken}`
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?principalId={principalId}&unitId={unitId}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken}`
List principal assignments for a role	`GET /v1/roles/{roleId}/assignments?maxResults={maxResults}&nextToken={nextToken}`
Revoke a role assignment	`DELETE /v1/roles/{roleId}/assignments`

List roles

Call GET /v1/roles?unitId={unitId}&roleName={roleName}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken} to get the list of roles defined for the specified unit or target entity that can be assigned to a user.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

Request format

GET /v1/roles?unitId={unitId}&roleName={roleName}&targetEntityId={targetEntityId}&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	You must specify either a `unitId` or a `targetEntityId`.
`targetEntityId`	The ID for the target entity.	String	You must specify either a `unitId` or a `targetEntityId`.
`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.example",
         "roleName": "{roleName}",
         "unitId": "amzn1.alexa.unit.did.example",
         "targetEntityId": "example-target-entity-id"         
      }
   ],
   "paginationContext": {
      "nextToken": null
   }
}

Response body parameters

Note: For unit-based roles, the response contains the same value in both the unitId and targetEntityId fields. For target-entity-based roles, the response contains the targetEntityId field, and the unitId field is null or empty.

Field	Description	Type
`roleId`	The role ID.	String
`roleName`	The role name.	String
`unitId`	The ID for the unit.	String
`targetEntityId`	The ID for the target entity.	String
`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.

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

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.example",
   "roleName": "Admin",
   "unitId": "amzn1.alexa.unit.did.example",
   "targetEntityId": "example-target-entity-id"
}

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
`targetEntityId`	The ID for the target entity 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?principalId={principalId}&unitId={unitId}&targetEntityId={targetEntityId}&maxResults={maxResults}&nextToken={nextToken} to get the list of role assignments for the specified principal for the specified unit or target entity.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

Request format

GET /v1/roles/assignments?principalId={principalId}&unitId={unitId}&targetEntityId={targetEntityId}&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.unit.did.{id}"`.	String	Yes
`targetEntityId`	Target entity 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?maxResults={maxResults}&nextToken={nextToken} to get the list of principal assignments for the specified role.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

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.

This operation is available in the following countries.

Healthcare	Hospitality	Residential	Senior Living	Core
US	US, UK, FR, CA, IT, DE	US, CA	US, UK, FR, CA, IT, DE	US

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.

Last updated: Mar 30, 2022