Skill Management API
Use the Skill Management API to manage your smart home skills for Alexa Smart Properties for residential homes.
About skill enablement for homes
For an introduction to Alexa skills, see What is the Alexa Skills Kit?.
An Alexa Smart Properties for residential home can be in the vacant, occupied or linked state. When a home is created, it's in the vacant state. When a resident moves in, you change the home's occupancy state from vacant to occupied. When the resident links their personal Amazon account with the home, the home's state changes to linked. See About home occupancy states.
Definitions
- Your skill — A skill that you develop and operate as an Alexa Smart Properties for residential developer, for example, a smart home skill.
- Home's skill account — A user account in your skill's account system that corresponds to a home unit, for example,
Unit 101 Account
. - Resident's skill account — A user account in your skill's account system that corresponds to a resident, for example, Jenny Smith's account with username
jennysmith@email.com
. - Home unit — An object in the Alexa Smart Properties for residential system that corresponds to a home in the home community, for example,
unit 101
. - Amazon account — A resident's personal Amazon account, for example, Jenny Smith's Amazon account with username
jennysmith@example.com
. - Linking — Linking your skill with a resident's Amazon customer account or with a (vacant or occupied) home unit.
Skill enablement for homes in the vacant state
For each home unit, you must create a home account and enable and link it with the home unit. This provides isolation for the home account to manage resources (such as smart home devices) that are associated only with that home.
Skill enablement for homes in the occupied state
When a home is in the occupied state, the resident might already have a skill account with your skill's service, but the resident's Amazon account is unknown. Your skill is enabled and linked to the home unit through the home account.
Skill enablement for homes in the linked state
When a resident links their personal Amazon account with the home, your skill is enabled on — and linked to — the resident's Amazon account. The home account's skill enablement and account linking are unchanged.
Get a skill enablement record for a unit
Call GET /v1/skills/{skillId}/enablements?unitId={unitId}
to get the skill enablement record for a specific skill for a unit.
Request format
GET /v1/skills/{skillId}/enablements?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
skillId |
The skill ID, in the format "amzn1.alexa.skill.{id}" . |
String | Yes |
Request query parameters
Field | Description | Type | Required |
---|---|---|---|
unitId |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String | Yes |
Success response header
HTTP/1.1 200 OK
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
{
"skill": {
"stage": "stage",
"id": "amzn1.ask.skill.skillId"
},
"unit": {
"id": "amzn1.alexa.unit.unitId"
},
"accountLink": {
"status": "LINKED"
},
"status": "ENABLED",
}
Response body parameters
Field | Description | Type |
---|---|---|
skill.stage |
Skill stage: development , certification , or live . |
Enum |
skill.id |
The unique identifier for a skill. | String |
unit.id |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String |
accountLink.status |
The current account linking status between the user's Amazon account and their account in your service: LINKED or NOT_LINKED . For skills that don't support account linking, NOT_LINKED is returned. |
String |
status |
Skill enablement status: ENABLING or ENABLED . |
Enum |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with 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 access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to perform the operation. |
404 | Not found | The requested enablement wasn't found. |
429 | Too many requests | Request has been throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
503 | Service Unavailable | Service is temporarily unavailable. |
List skill enablements for a unit
Call GET /v1/skills/enablements?unitId={unitId}
to get a list of all skill enablements for a unit.
Request format
GET /v1/skills/enablements?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 |
nextToken |
Continuation token returned in response object of previous list skill enablements response. For details, see Handling Pagination in Query Results. | String | No |
maxResults |
Maximum number of results to display. The value of this parameter must be between 1 and 10. Default is 10. | Integer | No |
Success response header
HTTP/1.1 200 OK
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
{
"paginationContext": {
"nextToken": "amzn1.ask.skill.tokenUUID"
},
"items": [
{
"skill": {
"stage": "live",
"id": "amzn1.ask.skill.skillId1"
},
"unit": {
"id": "amzn1.alexa.unit.unitId"
},
"accountLink": {
"status": "NOT_LINKED"
},
"status": "ENABLED"
},
{
"skill": {
"stage": "live",
"id": "amzn1.ask.skill.skillId2"
},
"unit": {
"id": "amzn1.alexa.unit.unitId"
},
"accountLink": {
"status": "NOT_LINKED"
},
"status": "ENABLED",
}
]
}
Response body parameters
Field | Description | Type |
---|---|---|
paginationContext |
The context contains all data needed to control pagination. | Object |
paginationContext.nextToken |
The token used to retrieve subsequent data. This token doesn't exist if there are no extra records. | String |
items |
A list of skill enablements. | List (Set) |
skill.stage |
Skill stage: development , certification , or live . |
Enum |
skill.id |
The unique identifier for a skill. | String |
unit.id |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String |
accountLink.status |
The current account linking status between the user's Amazon account and their account in your service: LINKED or NOT_LINKED . The accountLink object is present only for skills that support account linking. |
String |
status |
Skill enablement status: ENABLING or ENABLED . |
Enum |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with 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 access token is missing, expired, or invalid. |
403 | Forbidden | The user doesn't have permission to access the service. |
429 | Too many requests | Request has been throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
503 | Service Unavailable | Service is temporarily unavailable. |
Enable a skill for a unit
Call POST /v1/skills/{skillId}/enablements
to enable a skill for a unit.
Request format
POST /v1/skills/{skillId}/enablements HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
skillId |
The skill ID, in the format "amzn1.alexa.skill.{id}" . |
String | Yes |
Request body example
{
"unitId": "amzn1.alexa.unit.unitId",
"stage": "live",
"partitionName": "Home101-LivingRoom",
"accountLinkRequest": {
"redirectUri": "https://example.com",
"authCode": "3pauthcode",
"type": "AUTH_CODE"
}
}
Request body parameters
Field | Description | Type | Required |
---|---|---|---|
|
The unit ID, in the format |
String |
Yes |
|
Skill stage: |
Enum |
Yes |
|
A partition name is an identifier for a logical grouping of resources such as devices, endpoints, or skills. This parameter is a string containing a single partition name or a comma-separated list of partition names. A partition name is a single nonempty string that can contain alphanumeric characters and hyphens but not whitespace. Note: If there is an existing enablement for a given |
String |
No |
|
Account linking request information, as an AccountLinkRequest object. |
Object |
Yes, for skills that support account linking |
AccountLinkRequest object schema
Field | Description | Type | Required |
---|---|---|---|
|
The |
String |
Yes |
|
An OAuth 2.0 authorization code. This value is required to perform account linking. For details, see Authorization code grant flow. |
String |
Yes |
|
The type of account linking request, which is based on OAuth 2.0 authorization request protocols. Currently the only supported value is |
String |
Yes |
Success response header
HTTP/1.1 201 Created
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
{
"skill": {
"stage": "stage",
"id": "{skillId}"
},
"unit": {
"id": "{unitId}"
},
"accountLink": {
"status": "LINKED"
},
"status": "ENABLING",
}
Response body parameters
Field | Description | Type |
---|---|---|
skill.stage |
Skill stage: development or live . |
Enum |
skill.id |
The unique identifier for a skill, in the format "amzn1.ask.skill.{id}" . |
String |
unit.id |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String |
accountLink.status |
The current account linking status between the user's Amazon account and their account in your service: LINKED or NOT_LINKED . The accountLink object is present only for skills that support account linking. |
String |
status |
Skill enablement status: ENABLING or ENABLED . |
Enum |
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message. | String | No |
HTTP response codes
Status Code | Name | Description |
---|---|---|
201 | Created | The skill enablement was successfully created. |
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 skill ID or unit ID can't be found. |
429 | Too many requests | Request has been throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
503 | Service Unavailable | Service is temporarily unavailable. |
Disable a skill for a unit
Call DELETE /v1/skills/{skillId}/enablements?unitId={unitId}
to disable a skill for a unit.
Request format
DELETE /v1/skills/{skillId}/enablements?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request body
None.
Request parameters
Field | Description | Type | Required |
---|---|---|---|
unitId |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String | Yes |
skillId |
The skill ID, in the format "amzn1.alexa.skill.{id}" . |
String | Yes |
stage |
Skill stage: development , certification , or live . If present, the stage must be enabled. |
Enum | No |
Success response header
HTTP/1.1 200 OK
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 |
Success response parameters
None.
Error response
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
type |
The error type. | String | No |
message |
The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with 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 | The skill enablement was successfully deleted. |
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 skill ID or unit ID can't be found. |
429 | Too many requests | Request has been throttled. |
500 | Internal Server Error | The request couldn't be handled because of an internal service error. |
503 | Service Unavailable | Service is temporarily unavailable. |
Enable a skill for multiple units
Call POST /v1/skills/{skillId}/enablements/batch
to enable a skill for multiple units in a single request.
Request format
POST /v1/skills/{skillId}/enablements/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}
Request path parameters
Field | Description | Type | Required |
---|---|---|---|
skillId |
The skill ID, in the format "amzn1.alexa.skill.{id}" . |
String | Yes |
Request body example
The following example shows the body for a request to enable a skill for two units. The body contains two items, one for each unit.
{
"items": [
{
"itemId": 0,
"unitId": "amzn1.alexa.unit.unitId1",
"stage": "live",
"partitionName": "10-101", // Optional
"accountLinkRequest": { // Optional, only for skills that support account linking
"redirectUri": "https://redirecturi.com",
"authCode": "3pauthcode1",
"type": "AUTH_CODE"
}
},
{
"itemId": 1,
"unitId": "amzn1.alexa.unit.unitId2",
"stage": "live",
"partitionName": "11-101,11-102,11-103" // Optional
}
]
}
Request body parameters
Field | Description | Type | Required |
---|---|---|---|
|
A list of request items. Each item represents an enablement request for a single unit. |
Array |
Yes |
|
A unique identifier for the request item. Must be unique within the request. |
Integer |
Yes |
|
The unit ID, in the format |
String |
Yes |
|
Skill stage: |
Enum |
Yes |
|
A partition name is an identifier for a logical grouping of resources such as devices, endpoints, or skills. This parameter is a string containing a single partition name or a comma-separated list of partition names. Note: If there is an existing enablement for a given |
String |
No |
|
Account linking request information, as an AccountLinkRequest object. |
Object |
Yes, for skills that support account linking |
Success response
HTTP/1.1 202 Accepted
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 |
Success response parameters
None.
Error response header
HTTP/1.1 {ErrorCode}
{
"type": "{ErrorType}",
"message": "{ErrorMessage}"
}
Error response body examples
The following example shows an error response body for an entire request, not for individual items.
{
"errors": [
{
"status": 401,
"erorrCode": "INVALID_LWA_TOKEN",
"errorDescription": "The access token is invalid."
}
]
}
The following example shows an error response body for individual items.
{
"errors": [
{
"itemId": 0,
"status": 400,
"errorCode": "INVALID_PARAM",
"errorDescription": "unitId is missing or invalid"
},
{
"itemId": 20,
"status": 403,
"errorCode": "FORBIDDEN",
"errorDescription": "The operator doesn't have the right permission to perform the operation."
}
]
}
Error response parameters
Field | Description | Type | Required |
---|---|---|---|
|
A list of error responses, one for each request item. |
Array |
Yes |
|
The identifier for the request item. Optional if the error response is for the entire request and not for individual items. |
String |
No |
|
The response status code per request or request item. |
Integer |
Yes |
|
The error code for the error. |
Enum |
Yes |
|
A description of the error. |
String |
Yes |
HTTP response codes
Status code | errorDescription value | Scope |
---|---|---|
202 |
|
Request |
400 |
|
Request |
400 |
|
Request or Request item |
400 |
|
Request item |
400 |
|
Request |
401 |
|
Request |
403 |
|
Request item |
429 |
|
Request |
500 |
|
Request |
503 |
|
Request |