Skill Enablement REST API Reference
Use the Skill Enablement REST API to enable and disable an Alexa 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
- North America:
Authentication
Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA):
- To enable skills for a developer or other skill owner, see Get an Access Token for SMAPI.
- To enable skills for a customer and set up account linking, see Get an access token for the customer.
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.
AcceptGrant
directive.To get the access token for the customer to use in the Skill Enablement APIs
- 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. - Otherwise, get the authorization code from the Login with Amazon (LWA) authorization server.
Make sure to request access to thealexa::skills:account_linking
scope. The Amazon authorization code is valid for five minutes. - 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
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
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 |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Indicates stage of the skill. Until your skill is published, set to |
String |
Yes |
|
Header |
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 |
---|---|
|
Skill enabled for the specified customer and stage. |
|
Indicates that one or more properties in the request header or body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested skill or skill stage not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Enable skill and account link
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.
Request
To enable a skill and account link, you make a POST
request to the enablement
resource.
Request path and header example
POST /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 |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
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 |
---|---|---|---|
|
Indicates stage of the skill. Until your skill is published, set to |
String |
Yes |
|
Account linking information for your OAuth 2.0 server. |
Object |
Yes |
|
Type of OAuth 2.0 request. |
String |
Yes |
|
Authorization code for the customer. Alexa sends this code to your authorization server to exchange for access tokens. |
String |
Yes |
|
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 |
|
Used with the PKCE OAuth 2.0 protocol. |
String |
No |
Response
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 |
---|---|---|
|
Requested date for publication. |
Object |
|
Identifies the skill. |
String |
|
Indicates stage of the skill. Until your skill is published, set to |
String |
|
Identifies the user. |
Object |
|
Unique identifier for the customer. If the customer disables and re-enables the skill, this value might change. |
String |
|
Status of account linking between the customer's Amazon account and the customer's account in another system. |
Object |
|
Accounting linking status. |
String |
|
Enablement status of the skill.
|
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the skill and account linking statuses. |
|
Indicates that one or more properties in the request header or body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested skill or skill stage not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
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
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 |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
Header |
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 |
---|---|
|
Skill disabled for the specified customer and stage. |
|
Indicates that one or more properties in the request header or body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested skill or skill stage not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Disable skill and unlink account
Disable the specified skill for the customer and unlink the accounts.
Request
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.
Request path and header example
DELETE /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 |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Header |
LWA token. The access token must be specific to the customer and to your skill. For more details about access tokens, see Authentication. Note: Smart home skills can use the token that they received from the
AcceptGrant directive. |
String |
Yes |
Request body example
The request has no body.
Request body properties
The response has no body.
Response
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.
HTTP status codes
Status | Description |
---|---|
|
Successfully disabled the skill for the specified customer and unlinked the customer accounts. |
|
Indicates that one or more properties in the request header or body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested skill or skill stage not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Get account linking and skill status
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
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 |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Header |
LWA token. The access token must be specific to the customer and to your skill. For more details about access tokens, see Authentication. Note: Smart home skills can use the token that they received from the
AcceptGrant directive. |
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 |
---|---|---|
|
Requested date for publication. |
Object |
|
Identifies the skill. |
String |
|
Indicates stage of the skill. Until your skill is published, set to |
String |
|
Identifies the user. |
Object |
|
Unique identifier for the customer. If the customer disables and re-enables the skill, this value might change. |
String |
|
Status of account linking between the customer's Amazon account and the customer's account in another system. |
Object |
|
Accounting linking status. |
String |
|
Enablement status of the skill.
|
String |
HTTP status codes
Status | Description |
---|---|
|
Response body contains the skill and account linking statuses. |
|
Indicates that one or more properties in the request header or body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested skill or skill stage not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
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
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 |
---|---|---|---|---|
|
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 |
---|---|---|
|
Alexa endpoints. Use these endpoints in subsequent calls to the Skill Enablement APIs for the customer. |
Array of string |
HTTP status codes
Status | Description |
---|---|
|
Response body contains a list of Alexa endpoints. |
|
Indicates that one or more properties in the request header or body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested skill or skill stage not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
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
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 |
---|---|---|---|---|
|
Path |
Identifies the skill. |
String |
Yes |
|
Path |
Indicates stage of the skill. |
String |
Yes |
|
Header |
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 |
---|---|
|
Skill enabled for the specified customer and stage. |
|
Indicates that one or more properties in the request header or body aren't valid.
|
|
Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource. |
|
Indicates that the authorization token is valid, but the requested operation isn't allowed. |
|
Requested skill or skill stage not found. |
|
Permitted rate limit, specified as number of requests per unit of time, exceeded. Retry the request by using exponential back-off. |
|
Error occurred on the server. Retry the request by using exponential back-off. |
|
Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request. |
Related topics
- Quick Reference: Add Account Linking to an Alexa Skill
- Account Linking Concepts for Alexa Skills
- The OAuth 2.0 Authorization Framework (RFC 6749)
- OAuth.com
Last updated: Aug 01, 2024