Alexa Skill Activation API

You use the Alexa Skill Activation API to enable and disable an Alexa skill for a user, and link the user's Amazon account with an account in another service.

The endpoint you use for the Alexa Skill Activation API depends on where the user is located. Possible endpoints are https://api.amazonalexa.com, https://api.eu.amazonalexa.com, and https://api.fe.amazonalexa.com. To find this endpoint, see Get the endpoint for the user.

• Prerequisites
• Get the endpoint for the user
  • Request
  • Response
• Enable skill and link account
  • Request
  • Response
• Get account linking and skill status
  • Request
  • Response
• Disable skill and unlink account
  • Request
  • Response
• Type schemas
  • skillEnablement
  • Error

Prerequisites

Before calling the Alexa Skill Activation API, your service must obtain an Amazon access token for the user by using OAuth 2.0. To get an Amazon access token for the user, your service must:

1. Get an Amazon authorization code for the user – The Amazon authorization code will enable you to get the Amazon access token in the next step. Depending on your use case, you get the user's Amazon authorization code by making an HTTP GET request to the Alexa app URL (for app-to-app account linking) or the Login with Amazon (LWA) authorization server. For more information, see App-to-App Account Linking or Login with Amazon. In your request to get the user's Amazon authorization code, make sure to request access to the alexa::skills:account_linking scope, because the Amazon access token will need access to that scope. The Amazon authorization code is valid for 5 minutes.
2. Exchange the Amazon authorization code for an Amazon access token – To enable the skill and complete account linking using the Alexa Skill Activation API, you must have an Amazon access token. To get the Amazon access token, you call the LWA authorization server with the Amazon authorization code that you obtained previously. The Amazon access token expires in one hour. If you expect to call the Alexa Skill Activation API after that time, you must store the Amazon refresh token that LWA provided. The Amazon refresh token enables you to obtain a new Amazon access token that is valid for another hour.

For general information about account linking and Alexa skills, see Understand Account Linking.

Get the endpoint for the user

To get the endpoint to use when calling the Alexa Skill Activation API for a user, first make a GET request to the Alexa API Endpoint API. This API returns an endpoint based on where the user's Amazon account is registered. Use the returned endpoint when you call any of the Alexa Skill Activation API operations.

If the GET request returns more than one endpoint, then the Alexa service could not determine the correct endpoint for the user. In this case, when you call the Alexa Skill Activation API for the user, you must call each of the endpoints in sequence. Only one call will succeed.

Request

GET /v1/alexaApiEndpoint HTTP/1.1
Host: <api.amazonalexa.com, api.eu.amazonalexa.com, or api.fe.amazonalexa.com>
Content-Type: application/json
Authorization: "Bearer {Amazon Access Token}"

Parameters

Response

Sample responses

The following is an example of a success response that contains one endpoint:

HTTP/1.1 200 OK
Content-Type: application/json,
Cache-Control: no-cache
{
    "endpoints": [
        "api.amazonalexa.com"
    ]
}

The following is an example of a success response that contains multiple endpoints, which means that the correct endpoint could not be found:

HTTP/1.1 200 OK
Content-Type: application/json,
Cache-Control: no-cache
{
    "endpoints": [
        "api.amazonalexa.com",
        "api.eu.amazonalexa.com",
        "api.fe.amazonalexa.com"
    ]
}

Enable skill and link account

To enable the skill and link the account for the user, you make a POST request to the Alexa Skill Activation API. Use the endpoint that you found using Get the endpoint for the user.

Request

POST /v1/users/~current/skills/{skillId}/enablement HTTP/1.1
Host: <api.amazonalexa.com, api.eu.amazonalexa.com, or api.fe.amazonalexa.com>
Content-Type: application/json
Authorization: "Bearer {Amazon Access Token}"
// Body in raw JSON
{
    "stage": "<skill stage>",
    "accountLinkRequest": {
      "redirectUri": "https://yourRedirectURI",
      "authCode": "The user's authorization code from your authorization server",
      "type": "AUTH_CODE"
    }
}

Parameters

Response

Sample responses

The following is an example of a success response:

HTTP/1.1 201 CREATED
Content-Type: application/json
{
    "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.123456789"
    },
    "user": {
        "id": "amzn1.ask.account.123456789"
    },
    "accountLink": {
        "status": "LINKED"
    },
    "status": "ENABLED"
}

The following is an example of a failure response:

HTTP/1.1 403 FORBIDDEN
Content-Type: application/json
{
    "message": "The authentication token is invalid or doesn't have access to make this request"
}

Get account linking and skill status

To get information about the relationship between a user and a skill, such as the account linking status and whether the skill is enabled, you make a GET request to the Alexa Skill Activation API.

You must make this request in the same region where you enabled the skill and linked the account, which is the endpoint you found using Get the endpoint for the user. For example, if you enabled the skill and linked the account in https://api.eu.amazonalexa.com/, making a GET request in https://api.amazon.com will fail.

Request

GET /v1/users/~current/skills/{skillId}/enablement HTTP/1.1
Host: <api.amazonalexa.com, api.eu.amazonalexa.com, or api.fe.amazonalexa.com>
Content-Type: application/json
Authorization: "Bearer {Amazon Access Token}"

Parameters

Response

Sample responses

The following is an example of a success response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "skill": {
        "stage": "live",
        "id": "amzn1.ask.skill.123456789"
    },
    "user": {
        "id": "amzn1.ask.account.123456789"
    },
    "accountLink": {
        "status": "LINKED"
    },
    "status": "ENABLED"
}

The following is an example of a failure response:

HTTP/1.1 404 NOT FOUND
Content-Type: application/json
{
    "message": "The requested enablement could not be found"
}

Disable skill and unlink account

To disable the skill and unlink the account for the user, you make a DELETE request to the Alexa Skill Activation API.

You must make this request in the same region where you enabled the skill and linked the account, which is the endpoint you found using Get the endpoint for the user. For example, if you enabled the skill and linked the account in https://api.eu.amazonalexa.com/, making a DELETE request in https://api.amazon.com will fail.

Request

DELETE /v1/users/~current/skills/{skillId}/enablement HTTP/1.1
Host: <api.amazonalexa.com, api.eu.amazonalexa.com, or api.fe.amazonalexa.com>
Content-Type: application/json
Authorization: "Bearer {Amazon Access Token}"

Parameters

Response

Sample responses

The following is an example of a success response:

HTTP/1.1 204 NO CONTENT

The following is an example of a failure response:

HTTP/1.1 404 NOT FOUND
Content-Type: application/json
{
    "message": "The requested skill id and stage combination could not be found. Please verify that your inputs are correct."
}

Type schemas

skillEnablement

{
   "skill": {
      "id": "Your skill ID",      
      "stage": "your skill stage"
   },
   "user": {
      "id": "User ID"
   },
    "accountLink": {
      "status": "LINKED"
   },
   "status": "ENABLED"
}

EnablementStatus enumeration values

The account linking status can be one of the following values:

• ENABLED: The skill was successfully enabled.
• ENABLING: The enablement was initiated, but background processes are ongoing.
• ENABLING_FAILED: The user initiated an enablement, but a background process failed unrecoverably.
• DISABLED: The skill was previously enabled, but has since been disabled.
• DISABLING: The user removed their enablement for the skill, but background processes are still finishing.
• DISABLING_FAILED: The user removed their enablement for the skill, but a background process failed unrecoverably.
• NO_ASSOCIATION: The user has never enabled the skill. Most implementations should treat this like a 404.

Error