Skill Enablement REST API Reference

Use the Skill Enablement REST API to enable and disable a custom skill for a developer or an Amazon customer. If you enable a skill for a customer, the API links the customer's Amazon account with the customer's account in another system.

API endpoint

The endpoint of the Skill Enablement API depends on whether you invoke the API on behalf of a developer that owns the skill or on behalf of an Amazon customer:

  • For a developer skill owner, the endpoint is https://api.amazonalexa.com.
  • For an Amazon customer, the endpoint is based on where the customer's Amazon account is registered. To find the endpoint for a customer, use Get API endpoint. Valid endpoints are:
    • North America: https://api.amazonalexa.com
    • Europe: https://api.eu.amazonalexa.com
    • Far East: https://api.fe.amazon.com

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA):

Get an access token for the customer

To get an Amazon access token for the customer, you use the OAuth 2.0 authorization code grant flow.

To get the access token for the customer to use in the Skill Enablement APIs

  1. If you use App-to-App Account Linking, get the user's Amazon authorization code by making an HTTP GET request to the Alexa app URL.
    The Amazon authorization code enables you to get the access token.
  2. Otherwise, get the authorization code from the Login with Amazon (LWA) authorization server.
    Make sure to request access to the alexa::skills:account_linking scope. The Amazon authorization code is valid for five minutes.
  3. With the Amazon authorization code that you just received, call LWA to exchange the authorization code for an Amazon access token.
    For details, see LWA Access Token Request. The Amazon access token expires in one hour. If you expect to call the Skill Enablement API after that time, you must store the Amazon refresh token that LWA provides, and then call LWA to exchange the refresh token for a new Amazon access token.

For general information about account linking and Alexa skills, see Add Account Linking to Your Alexa Skill.

Operations

The Skill Enablement API includes the following operations. Each operation is for a developer skill owner or for a customer. Make sure to select the right API for your implementation.

Operation HTTP method and URI

Enable skill

PUT /v1/skills/{skillId}/stages/{stage}/enablement

Enable skill and account link

POST /v1/users/~current/skills/{skillId}/enablement

Disable skill

DELETE /v1/skills/{skillId}/stages/{stage}/enablement

Disable skill and unlink account

DELETE /v1/users/~current/skills/{skillId}/enablement

Get API endpoint

GET /v1/alexaApiEndpoint

Get account linking and skill status

GET /v1/users/~current/skills/{skillId}/enablement

Get skill enablement status

GET /v1/skills/{skillId}/stages/{stage}/enablement

Enable skill

Enable the specified skill stage for the developer or other skill owner. If another stage is enabled, that stage is disabled, and then the specified stage is enabled.

Request

To enable a skill, you make a PUT request to the enablement resource.

Request path and header example

Copied to clipboard.

PUT /v1/skills/{skillId}/stages/{stage}/enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill. Until your skill is published, set to development.
Valid values: development, live.

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 204 No Content that indicates that the skill is enabled. 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.

HTTP status codes

Status Description

204 No Content

Skill enabled for the specified customer and stage.

400 Bad Request

Indicates that one or more properties in the request header or body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Incorrect endpoint for customer.",
     "code": "incorrectEndpoint"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn'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 skill or skill stage not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can 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.

Enable the specified skill for the specified customer, and then link the customer's Amazon account to the customer's account in another system. For details about how this API fits into app-to-app account linking, see How it works.

To enable a skill and account link, you make a POST request to the enablement resource.

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token. The access token must be specific to the customer and to your skill. For more details about access tokens, see Authentication.

String

Yes

Request body example

{
    "stage": "live",
    "accountLinkRequest": {
        "redirectUri": "https://yourRedirectURI",
        "authCode": "someToken1",
        "type": "AUTH_CODE"
    }
}

Request body properties

Property Description Type Required

stage

Indicates stage of the skill. Until your skill is published, set to development.
Valid values: development, live.

String

Yes

accountLinkRequest

Account linking information for your OAuth 2.0 server.

Object

Yes

accountLinkRequest.type

Type of OAuth 2.0 request.
Valid value: AUTH_CODE.

String

Yes

accountLinkRequest.authCode

Authorization code for the customer. Alexa sends this code to your authorization server to exchange for access tokens.

String

Yes

accountLinkRequest.redirectUri

Endpoint to retrieve access tokens. This URI must be the same as the redirect URI that you included in the authorization request to object the customer's authorization code.

String

Yes

accountLinkRequest.authCodeVerifier

Used with the PKCE OAuth 2.0 protocol.

String

No

A successful response returns HTTP 201 Created, along with the skill enablement 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

{
    "skill": {
        "id": "amzn1.ask.skill.1",
        "stage": "live"
    },
    "user": {
        "id": "amzn1.ask.account.1"
    },
    "accountLink": {
        "status": "LINKED"
    },
    "status": "ENABLED"
}

Response body properties

Property Description Type

skill

Requested date for publication.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

Object

skill.id

Identifies the skill.

String

skill.stage

Indicates stage of the skill. Until your skill is published, set to development.
Valid values: development, live.

String

user

Identifies the user.

Object

user.id

Unique identifier for the customer. If the customer disables and re-enables the skill, this value might change.

String

accountLink

Status of account linking between the customer's Amazon account and the customer's account in another system.

Object

accountLink.status

Accounting linking status.
Valid values: LINKED, NOT_LINKED.

String

status

Enablement status of the skill.
Valid values:

  • ENABLED: Skill was successfully enabled.
  • ENABLING: Enablement was initiated, but background processes are ongoing.
  • ENABLING_FAILED: Customer initiated an enablement, but a background process failed and isn't recoverable.
  • DISABLED: Skill was previously enabled, but the skill is disabled now.
  • DISABLING: Customer removed their enablement for the skill, but background processes are still finishing.
  • DISABLING_FAILED: Customer removed their enablement for the skill, but a background process failed and isn't recoverable.
  • NO_ASSOCIATION: Customer never enabled the skill. Treat this status like a 404.

String

Status Description

201 Created

Response body contains the skill and account linking statuses.

400 Bad Request

Indicates that one or more properties in the request header or body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Incorrect endpoint for customer.",
     "code": "incorrectEndpoint"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn'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 skill or skill stage not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can 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.

Disable skill

Disable the specified skill for the developer or other skill owner.

Request

To disable a skill, you make a PUT request to the enablement resource.

Request path and header example

Copied to clipboard.

DELETE /v1/skills/{skillId}/stages/{stage}/enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

String

Yes

access token

Header

LWA token.

String

Yes

Request body example

The request has no body.

Request body properties

The response has no body.

Response

A successful response returns HTTP 204 No Content that indicates the skill is disabled. 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.

HTTP status codes

Status Description

204 No Content

Skill disabled for the specified customer and stage.

400 Bad Request

Indicates that one or more properties in the request header or body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Incorrect endpoint for customer.",
     "code": "incorrectEndpoint"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn'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 skill or skill stage not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can 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.

Disable the specified skill for the customer and unlink the accounts.

To disable a skill, you make a DELETE request to the enablement resource. You must make this request to the same endpoint that you used in Enable skill and account link.

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token. The access token must be specific to the customer and to your skill. For more details about access tokens, see Authentication.

String

Yes

Request body example

The request has no body.

Request body properties

The response has no body.

A successful response returns HTTP 200 OK that indicates the skill is disabled and the accounts are unlinked. 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

Successfully disabled the skill for the specified customer and unlinked the customer accounts.

400 Bad Request

Indicates that one or more properties in the request header or body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Incorrect endpoint for customer.",
     "code": "incorrectEndpoint"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn'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 skill or skill stage not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can 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.

Check whether the specified skill is enabled for the customer, and then check whether the customer's Amazon account and the customer's account in another system are linked. You must make this request to the same endpoint that you used in Enable skill and account link.

Request

To get the account linking and skill status, you make a GET request to the enablement resource.

Request path and header example

Copied to clipboard.

GET /v1/users/~current/skills/{skillId}/enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

access token

Header

LWA token. The access token must be specific to the customer and to your skill. For more details about access tokens, see Authentication.

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 skill and account linking statuses. 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

{
    "skill": {
        "id": "amzn1.ask.skill.1",
        "stage": "live"
    },
    "user": {
        "id": "amzn1.ask.account.1"
    },
    "accountLink": {
        "status": "LINKED"
    },
    "status": "ENABLED"
}

Response body properties

Property Description Type

skill

Requested date for publication.
Defined in ISO 8601 format, YYYY-MM-DDThh:mm:ssZ.

Object

skill.id

Identifies the skill.

String

skill.stage

Indicates stage of the skill. Until your skill is published, set to development.
Valid values: development, live.

String

user

Identifies the user.

Object

user.id

Unique identifier for the customer. If the customer disables and re-enables the skill, this value might change.

String

accountLink

Status of account linking between the customer's Amazon account and the customer's account in another system.

Object

accountLink.status

Accounting linking status.
Valid values: LINKED, NOT_LINKED.

String

status

Enablement status of the skill.
Valid values:

  • ENABLED: Skill was successfully enabled.
  • ENABLING: Enablement was initiated, but background processes are ongoing.
  • ENABLING_FAILED: Customer initiated an enablement, but a background process failed and isn't recoverable.
  • DISABLED: Skill was previously enabled, but the skill is disabled now.
  • DISABLING: Customer removed their enablement for the skill, but background processes are still finishing.
  • DISABLING_FAILED: Customer removed their enablement for the skill, but a background process failed and isn't recoverable.
  • NO_ASSOCIATION: Customer has never enabled the skill. Treat this status like a 404.

String

HTTP status codes

Status Description

200 OK

Response body contains the skill and account linking statuses.

400 Bad Request

Indicates that one or more properties in the request header or body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Incorrect endpoint for customer.",
     "code": "incorrectEndpoint"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn'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 skill or skill stage not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can 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.

Get API endpoint

Get the Alexa API endpoint for the specified customer. The returned endpoint is based on where the customer's Amazon account is registered. Use this endpoint when you call the Skill Enablement APIs for the customer.

If the request returns more than one endpoint, then the Alexa service couldn't determine the correct endpoint for the customer. When you call the Skill Enablement API, you must call each of the endpoints in sequence. Only one endpoint will succeed.

Request

To get the API endpoint, you make a GET request to the alexaApiEndpoint resource.

Request path and header example

Copied to clipboard.

GET /v1/alexaApiEndpoint
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}
Accept: application/json

Request path and header parameters

Parameter Located in Description Type Required

access token

Header

LWA token. The access token must be specific to the customer and to your skill. For more details about access tokens, see Authentication.

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 a list of Alexa endpoints. On error, the response returns the appropriate HTTP status code and includes a response body with an error code and human readable message. If the status code is 5XX, call the Skill Enablement APIs by using the following endpoints in sequence:

  • https://api.amazonalexa.com
  • https://api.eu.amazonalexa.com
  • https://api.fe.amazonalexa.com

Response body example

The following example shows a response.

{
    "endpoints": [
        "api.amazonalexa.com"
    ]
}

Response body properties

Property Description Type

endpoints[]

Alexa endpoints. Use these endpoints in subsequent calls to the Skill Enablement APIs for the customer.

Array of strings

HTTP status codes

Status Description

200 OK

Response body contains a list of Alexa endpoints.

400 Bad Request

Indicates that one or more properties in the request header or body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Incorrect endpoint for customer.",
     "code": "incorrectEndpoint"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn'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 skill or skill stage not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can 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.

Get skill enablement status

Check that the specified skill is enabled for the customer. The accessToken specifies the developer or other skill owner.

Request

To get the skill enablement status, you make a GET request to the enablement resource.

Request path and header example

Copied to clipboard.

GET /v1/skills/{skillId}/stages/{stage}/enablement
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter Located in Description Type Required

skillId

Path

Identifies the skill.
Valid values: 1 – 255 characters.

String

Yes

stage

Path

Indicates stage of the skill.
Valid values: development, live.

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 204 No Content that indicates that the skill is enabled. 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.

HTTP status codes

Status Description

204 No Content

Skill enabled for the specified customer and stage.

400 Bad Request

Indicates that one or more properties in the request header or body are invalid.
The following example shows the response body with the error and message.

{
     "message": "Incorrect endpoint for customer.",
     "code": "incorrectEndpoint"
}

401 Unauthorized

Request didn't include the authorization token or the token is invalid or expired. Or, the client doesn'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 skill or skill stage not found.

429 Too Many Requests

Skill has exceeded the permitted rate limit (specified number of requests per unit of time). The skill can retry the request by using exponential back-off.

500 Server Error

Error occurred on the server. The skill can 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.