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
- Enable skill and link account
- Get account linking and skill status
- Disable skill and unlink account
- Type schemas
- Related topics
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:
- 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. - 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:
|
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 |
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"
]
}
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
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. | |
400 |
Bad request. Possible causes:
|
Error |
403 |
Forbidden. Possible causes:
|
Error |
404 |
Not found. Possible causes:
|
Error |
409 |
Conflict. Possible causes:
|
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. | |
403 |
Forbidden. Possible causes:
|
Error |
404 |
Not found. Possible causes:
|
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"
}
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
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:
|
Error |
404 |
Not found. Possible causes:
|
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 |