Consent Framework REST API Reference

Use the Consent Framework REST API in your property skill or feature to view and reset the consent status for resident units. You can't provide Alexa Smart Properties (ASP) features and services that use personal health information until the resident grants permission. For more details, see Consent Framework in Alexa Smart Properties.

API endpoint

The endpoint of the Consent Framework API is https://api.eu.amazonalexa.com.

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.

Access to consent information is based on the permission scopes enabled for your skill and granted by the customer. Include the following permission scope when you request an access token.

Permission scope Description

alexa::enterprise:management

Allows your skill to access the consent framework.

Operations

The Consent Framework API includes the following operations.

Operation HTTP method and URI

Get consent status for unit

GET /v2/units/{unitId}/consent?consentType={consentType}

Reset consent for unit

PUT /v2/units/{unitId}/consent/reset

Get the consent status for the specified unit. The status reflects whether the resident granted permission to use their personal health information.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

None

None

DE, ES, FR, IT, UK

None

To get consent, you make a GET request to the /v2/units/{unitId}/consent resource.

Parameter Located in Description Type Required

unitId

Path

Identifies the unit.
Format as amzn1.alexa.unit.did.{id}.

String

Yes

consentType

Path

Identifies the type of consent.
Valid values: health_data.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the consent status. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

{
    "consentStatus": "NO_CONSENT"
}

Response body properties

Property Description Type

consentStatus

Status of the specified unit for the selected consentType. For valid values, see Status values.

String

Status values

The following Consent Framework API supports the following status values.

Status value Description

NO_CONSENT

Indicates no consent is present or consent was reset.

DENIED

Indicates the user denied the consent.

REVOKED

Indicates that the user revoked consent after granting it previously.

GRANTED

Indicates that the user granted consent.

Status Description

200 OK

Response body contains the consent status.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Reset consent for the specified unit. This operation changes the consent status to NO_CONSENT and removes any personal health information from the device.

This operation is available in the following countries.

Healthcare Hospitality Senior Living Core

None

None

DE, ES, FR, IT, UK

None

To reset consent, you make a PUT request to the /v2/units/{unitId}/consent resource.

Parameter Located in Description Type Required

unitId

Path

Identifies the unit.
Format as amzn1.alexa.unit.did.{id}.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

Copied to clipboard.

{
    "consentType" : "health_data"
}

Request body properties

Property Description Type Required

consentType

Identifies the type of consent.
Valid values: health_data.

String

Yes

A successful response returns HTTP 200 OK. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message.

Response body example

The response has no body.

Response body properties

The response has no body.

Status Description

200 OK

Consent status reset successfully.

400 Bad Request

Indicates that one or more properties in the request body aren't valid.
The following example shows the response body with the error code and message.

{
     "message": "The property is outside the allowed range.",
     "code": "INVALID_STRING_LENGTH"
}

401 Unauthorized

Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.

403 Forbidden

Indicates that the authorization token is valid, but the requested operation isn't allowed.

404 Not Found

Requested resource not found.

429 Too Many Requests

Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. Retry the request by using exponential back-off.

503 Service Unavailable

Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Was this page helpful?

Last updated: Oct 31, 2024