Skill Management API
Use the Skill Management API to manage your smart home skills for Alexa for Residential homes.
About skill enablement for homes
For an introduction to Alexa skills, see What is the Alexa Skills Kit?.
An Alexa 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 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 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 skill enablement record
Call GET /v1/skills/{skillId}/enablements?unitId={unitId}
to get the skill enablement record for a specific skill for a unit.
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 |
stage |
Skill stage: development , certification , or live . If present, the stage must be enabled. |
Enum |
No |
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 . If present, the stage must be enabled. |
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. The accountLink object is present only for skills that support account linking. |
String. Either LINKED or NOT_LINKED . |
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 all skill enablements
Call GET /v1/skills/enablements?unitId={unitId}
to get a list of all skill enablements for a unit.
GET /v1/skills/enablements?unitId={unitId}&stage={stage}&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 |
stage |
Skill stage: development , certification , or live . If present, the stage must be enabled. |
Enum |
No |
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 |
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 . If present, the stage must be enabled. |
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. The accountLink object is present only for skills that support account linking. |
String. Either LINKED or NOT_LINKED . |
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
Call POST /v1/skills/{skillId}/enablements
to enable a skill for a unit.
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",
"accountLinkRequest": {
"redirectUri": "https://example.com",
"authCode": "3pauthcode",
"type": "AUTH_CODE"
}
}
Request body parameters
Field |
Description |
Type |
Required |
unitId |
The unit ID, in the format "amzn1.alexa.unit.did.{id}" . |
String |
Yes |
stage |
Skill stage: development , certification , or live . If present, the stage must be enabled. |
Enum |
No |
accountLinkRequest |
Account linking request information. |
Object |
Yes, for skills that support account linking |
accountLinkRequest.redirectUri |
The redirect_uri parameter that was included in the authorization request to your OAuth 2.0 server to obtain the user's authorization code. This enables Amazon to retrieve access tokens from your token server. This URL must be opaque to Amazon. |
String |
Yes, for skills that support account linking |
accountLinkRequest.authCode |
A third-party cloud's OAuth 2.0 "Authorization Code." This value is required to perform account linking. For details, see Authorization code grant flow. |
String |
Yes, for skills that support account linking |
accountLinkRequest.type |
The type of account linking request, which is based on OAuth 2.0 authorization request protocols. |
String. Must be AUTH_CODE . |
Yes, for skills that support account linking |
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 , certification , or live . If present, the stage must be enabled. |
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. The accountLink object is present only for skills that support account linking. |
String. Either LINKED or NOT_LINKED . |
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
Call DELETE /v1/skills/{skillId}/enablements?unitId={unitId}
to disable a skill for a unit.
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 |
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 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. |