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 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

Request query parameters

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

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

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

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

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

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

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

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

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

AccountLinkRequest object schema

Success response header

HTTP/1.1 201 Created
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
  "skill": {
    "stage": "stage",
    "id": "{skillId}"
  },
  "unit": {
    "id": "{unitId}"
  },
  "accountLink": {
    "status": "LINKED"
  },
  "status": "ENABLING",
}

Response body parameters

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

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

Success response header

HTTP/1.1 200 OK
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Success response parameters

None.

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

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

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

Success response

HTTP/1.1 202 Accepted
Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

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

HTTP response codes