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.

Operations

The Skill Management API includes the following operations.

Description HTTP method and path

Get a skill enablement record for a unit

GET /v1/skills/{skillId}/enablements?unitId={unitId}

List skill enablements for a unit

GET /v1/skills/enablements?unitId={unitId}

Enable a skill for a unit

POST /v1/skills/{skillId}/enablements

Disable a skill for a unit

DELETE /v1/skills/{skillId}/enablements?unitId={unitId}

Enable a skill for multiple units

POST /v1/skills/{skillId}/enablements/batch

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

Skill ID, in the format "amzn1.alexa.skill.{id}".

String

Yes

Request query parameters

Field Description Type Required

unitId

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

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

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

Unique identifier for a skill.

String

unit.id

Unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

accountLink.status

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

type

Error type.

String

message

Error message for the error.

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 skill ID or unit ID can't be 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.

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

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

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

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

Context contains all data needed to control pagination.

Object

paginationContext.nextToken

Token used to retrieve subsequent data. This token doesn't exist if there are no extra records.

String

items

List of skill enablements.

List (Set)

skill.stage

Skill stage: development, certification, or live.

Enum

skill.id

Unique identifier for a skill.

String

unit.id

Unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

accountLink.status

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

type

Error type.

String

message

Error message for the error.

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.

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

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

unitId

The unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

Yes

stage

Skill stage: development or live.

Enum

Yes

partitionName

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.
For example, "Home-101" and "Home101, Home202" are valid values for this parameter. The following aren't valid values: "" (empty list), "Home101, ,Home202" (not properly comma-separated), "Home 101" (contains whitespace).

String

No

accountLinkRequest

Account linking request information, as an AccountLinkRequest object.

Object

Yes, for skills that support account linking

Field Description Type Required

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

authCode

An OAuth 2.0 authorization code. This value is required to perform account linking. For details, see Authorization code grant flow.

String

Yes

type

The type of account linking request, which is based on OAuth 2.0 authorization request protocols. Currently the only supported value is AUTH_CODE.

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

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


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

Unique identifier for a skill, in the format "amzn1.ask.skill.{id}".

String

unit.id

Unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

accountLink.status

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

type

Error type.

String

message

Error message for the error.

String

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

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.

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

Unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

Yes

skillId

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

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

Success response parameters

None.

Error response

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

Error response parameters

Field Description Type

type

Error type.

String

message

Error message for the error.

String

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

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.

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

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

items

A list of request items. Each item represents an enablement request for a single unit.

Array

Yes

itemId

A unique identifier for the request item. Must be unique within the request.

Integer

Yes

unitId

The unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

Yes

stage

Skill stage: development, certification, or live.

Enum

Yes

partitionName

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.
For example, "Home101" and "Home101, Home202" are valid values for this parameter. The following are not valid values: "" (empty list), "Home101, ,Home202" (not properly comma-separated), "Home 101" (contains whitespace).

String

No

accountLinkRequest

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

X-Amzn-RequestId

Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.

String

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

errors

A list of error responses, one for each request item.

Array

Yes

itemId

The identifier for the request item. Optional if the error response is for the entire request and not for individual items.

String

No

status

The response status code per request or request item.

Integer

Yes

errorCode

The error code for the error.

Enum

Yes

errorDescription

A description of the error.

String

Yes

HTTP response codes

Status Code Name Description

202

Accepted

The request was accepted.

400

Bad Request

The request is malformed or is missing one or more required parameters. Example reasons:
  • The skillId is missing or invalid.
  • The unitId is missing or invalid.
  • The requested skillId and stage combination couldn't be found.
  • The number of request items exceeds the limit.

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.