Step 6: Enable Your Skill to Complete Account Linking

---

Now that your app has the user's Amazon access token, your backend server can call the Alexa Skill Enablement API to enable the skill. As part of this step, the Alexa service sends an access token request to your token server for access to the user's resources in your system.

Enable the skill and complete account linking

Your backend app calls the Alexa Skill Enablement API endpoint with the following parameters:

• User's Amazon access token in the Authorization header
• Authorization code for the user's account in your service, obtained from your authorization server.
• Redirect URI for your app
• Authorization type (AUTH_CODE)

As part of the API, the Alexa service sends an access token request with the your authorization code to your token server URL. The access token that Alexa receives in the response allows your skill to access the user's resources in your system.

HTTP Request

Make a request to the Enable skill and account link enablement resource. Set the API endpoint based on where the user's account is registered.

POST /v1/users/~current/skills/{skillId}/enablement HTTP/1.1
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: "Bearer {Amazon access token}"
{
    "stage": "development or live",
    "accountLinkRequest": {
    "redirectUri": "https://yourRedirectURI",
    "authCode": "Your user's authorization code from your authorization server",
    "type": "AUTH_CODE"
    }
}

HTTP response

On success, the Alexa Skill Enablement API returns HTTP 201 Created, indicating that the skill is enabled and the accounts are linked.

HTTP 201
Content-Type: application/json
{
  "skill": {
    "stage": "your skill stage",
    "id": "your skill id"
  },
  "user": {
    "id": "User ID"
  },
  "accountLink": {
    "status": "LINKED"
  },
  "status": "ENABLED"
}

For possible errors and the associated message to show the user, see Errors when calling the Alexa Skill Enablement API.

Disable the skill and unlink the accounts

If the user deletes your service, you can disable the skill and unlink the account for the user. To do so, make a Disable skill and unlink account request to the Alexa Skill Enablement API.

Example skill enablement and linking

In this example, the app enables the skill and completes account linking.

const _ = require('lodash');
const axios = require('axios');
const {config} = require('../config/skillconfig');
const {getAccessTokenByAuthcode} = require('./oauthrequests');

// Request to the Alexa Skill Enablement API in the backend
const AlexaServiceRequest = (() => {
    const header = (amazonAccessToken) => {
        return {
            "headers": {
                "Content-Type": "application/json",
                "Authorization": "Bearer " + amazonAccessToken
            }
        };
    };

    const body = (userAuthCode) => {
        return {
            "stage": config.skillConfig.stage,
            "accountLinkRequest": {
                "redirectUri": config.skillConfig.redirect_uri,
                "authCode": userAuthCode,
                "type": "AUTH_CODE"
            }
        }
    }

    return {
        createEnablement: (amazonAccessToken, userAuthCode) => {
            return {
                header: header(amazonAccessToken),
                body: body(userAuthCode)
            }
        }
    }
})();

function createEnablementWithAccountLink(amazonAuthCode, userAuthcode, state) {

    // Exchange Amazon OAuth Code for Amazon Access Token
    const tokenPromise = getAccessTokenByAuthcode(amazonAuthCode, state);
    return tokenPromise.then((res) => {
        if (!_.has(res, 'data.access_token')) {
            throw Error("Amazon AccessToken is invalid");
        }
        console.log(res);
        const amazonAccessToken = res.data.access_token;

        // Call the Alexa Skill Enablement API to create enablement
        const createEnablementRequest = AlexaServiceRequest.createEnablement(amazonAccessToken, userAuthcode);
        return sendPostRequests(config.endpoints.alexaServiceEndpoints, createEnablementRequest.body, createEnablementRequest.header);
    });
}

// Post enablement to the Alexa Skill Enablement API
function sendPostRequests(endpoints, body, header) {
    var alexaServicePromises = []

    // Post for each Alexa Skill Enablement API regional endpoint for the user
    endpoints.forEach((endpoint)=> {
        alexaServicePromises.push(axios.post(endpoint, body, header));
    });
    return new Promise((resolve, reject)=> {
        var failures = 0;
        alexaServicePromises.forEach((promise)=> {
            promise.then((res)=> {
                if (res.status == 201) {
                    resolve(res.data);
                } else {
                    if (++failures == alexaServicePromises.length) {
                        reject(res.data);
                    }
                }
            }).catch((err)=> {
                if (++failures == alexaServicePromises.length) {
                    reject(err.data);
                }
            })
        })
    });
}

Errors

If an error occurs when your app calls the Alexa Skill Enablement API to enable and link the user's account, the API responds with a status code that says why the request failed. Otherwise, the API responds with an HTTP 2XX status code. For details about why the skill activation request failed, check the message parameter of the JSON response.

HTTPS status code	Message to show to user	Possible causes
400 Bad Request	We are experiencing a problem connecting with Alexa to link your account. Please try again later.	Missing skill_id, stage, accountLinkingRequest.authCode, accountLinkingRequest.redirectUri, and/or accountLinkingRequest.Type Error requesting your app's access and refresh token pair from your app's token server
403 Forbidden	We are experiencing a problem connecting with Alexa to link your account. Please try again later.	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 skill_id provided in the request The user isn't entitled to enable the skill with the specified skill_id provided in the request
404 Not Found	We are experiencing a problem connecting with Alexa to link your account. Please try again later.	Invalid skill_id and/or stage
500 Server Error	Sorry, Alexa encountered an unexpected error while trying to link your account. Please try again.	Unexpected server error Problem linking accounts with your app's OAuth server

• Previous – Step 5: Make an Access Token Request
• Next – Step 7: Display Account Linking Status

---

---

Last updated: frontmatter-missing