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

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

Name Located in Description Required Type
Authorization Header An Amazon access token from LWA. The Amazon access token is specific to the user and to your skill. For more information about access tokens, see Authorization. Yes String

Response

Code Description Type
200 Success response, which contains an array of Alexa endpoints. If the array contains a single endpoint, then that is the correct endpoint for the user. If the array contains more than one endpoint, then the Alexa service could not determine which endpoint to use 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.

Array of strings
403

Forbidden. Possible causes:

  • The Amazon access token is invalid or doesn't have access to make this request
 Error
5xx

Could not find the correct endpoint for the user. In this case, when you call the Alexa Skill Activation API for the user, you must call https://api.amazonalexa.com, https://api.eu.amazonalexa.com, and https://api.fe.amazonalexa.com in sequence. Only one call will succeed.

 Error

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"
    ]
}

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

Name Located in Description Required Type
Authorization Header An Amazon access token from LWA. The Amazon access token is specific to the user and to your skill. For more information about access tokens, see Authorization. Yes String
skillId Path The skill ID of the skill to enable. Yes String
stage Body The stage of the skill. Until your skill is published, set stage to development. When your skill is published, use live. Yes String. Either development or live.
accountLinkRequest Body Account linking request information. Yes Object
accountLinkRequest.redirectUri Body 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. Yes String
accountLinkRequest.authCode Body The user's authorization code from your authorization server. Yes String
accountLinkRequest.type Body The type of account linking request, which is based on OAuth 2.0 authorization request protocols. Yes String. Must be AUTH_CODE.

Response

Code Description Type
201 Success response, which contains a skill enablement object.

skillEnablement object
400

Bad request. Possible causes:

  • Missing skillId, stage, accountLinkingRequest.authCode, accountLinkingRequest.redirectUri, and/or accountLinkingRequest.Type
  • Error requesting your service's access/refresh token pair from your service's token server
 Error
403

Forbidden. Possible causes:

  • The Amazon access token is invalid
  • The Amazon access token doesn't have the user's consent to enable the skill
  • The Amazon access token doesn't belong to the skillId provided in the request
  • The user is not entitled to enable the skill with the specified skill_id provided in the request
 Error
404

Not found. Possible causes:

  • Invalid skillId and/or stage
 Error
409

Conflict. Possible causes:

  • Skill is already enabled
 Error
500

Internal server error.

 Error

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

Name Located in Description Required Type
Authorization Header An Amazon access token from LWA. The Amazon access token is specific to the user and to your skill. For more information about access tokens, see Authorization. Yes String
skillId Path The skill ID of the skill. Yes String

Response

Code Description Type
200 Success response, which contains a skill enablement object.

skillEnablement object
403

Forbidden. Possible causes:

  • The Amazon access token doesn't have access to the user's skill enablement
  • The Amazon access token doesn't belong to the skillId provided in the request
  • The Amazon access token has expired and must be refreshed
 Error
404

Not found. Possible causes:

  • Invalid skillId
  • The skill is not enabled
 Error
500 Internal server error Error

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

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

Name Located in Description Required Type
Authorization Header An Amazon access token from LWA. The Amazon access token is specific to the user and to your skill. For more information about access tokens, see Authorization. Yes String
skillId Path The skill ID of the skill to disable. Yes String

Response

Code Description Type
204 Success response. HTTP 204 Content-Type: application/json
403

Forbidden. Possible causes:

  • The Amazon access token doesn't have access to the user's skill enablement
  • The Amazon access token doesn't belong to the skillId provided in the request
  • The Amazon access token has expired and must be refreshed
 Error
404

Not found. Possible causes:

  • Invalid skillId
  • The skill is not enabled
 Error
500 Internal server error Error

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"
}
Name Description Type
skill Object that contains the skill ID and stage. Object
skill.id The skill ID of the skill. String
skill.stage The stage of the skill. String. Either development or live. Until your skill is published, set stage to development. When your skill is published, use live.
user Object that contains the user ID. Object
user.id Unique identifier for the user. This changes if the user disables and re-enables the skill. String
accountLink Object that contains the current account linking status. Object
accountLink.status The current account linking status between the user's Amazon account and their account in your service. String. Either LINKED or NOT_LINKED.
status The current enablement status of the skill. String of type EnablementStatus.

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

Name Description Type
message Readable description of error String