Requirements for Account Linking for Alexa Skills

This topic lists the account linking implementation requirements for Alexa skills. To see which skill types require account linking, see Does my skill need account linking?

For an explanation of account linking concepts, see Account Linking Concepts for Alexa Skills. For the user experience, see How Users Experience Account Linking for Alexa Skills.

Authentication framework requirements

Your system must meet the following requirements:

Authorization URI requirements

When the user initiates account linking, the Alexa app goes to your authorization URI. This URI is the entry point to the functionality on your authorization server that: 1) displays a log-in page for the user to log into your system, 2) authenticates the user in your system, 3) generates an authorization code that identifies the user, and 4) passes the authorization code to the Alexa app.

Your authorization URI must meet the following requirements:

  • Protocol – It must be accessible over HTTPS on port 443.
  • User interface – It must provide a mobile-friendly log-in page, because this page will be displayed within the Alexa app. The log-in page cannot open any pop-up windows or launch any JavaScript alerts or message boxes. If the user encounters an error (for example, they enter the wrong password), the log-in page should display the error.
  • Functionality – The authorization URI must:
    • Accept the user's credentials and then authenticate the user within your system.
    • Generate an authorization code that the Alexa app can pass to the access token URI to retrieve an access token that uniquely identifies the user in your system.
    • Keep track of the state value that the Alexa app passes in the query string, because your authorization server must use that same state value when it calls the Alexa redirect URI for that particular account linking request.
  • Redirection – The following requirements apply to redirecting the user to the Alexa app:
    • After authenticating the user, the log-in page must redirect the user to the Alexa redirect URI that the Alexa app provided as a query parameter to the authorization URI, and include the state and code values in the Alexa redirect URI query string. For example: https://pitangui.amazon.com/api/skill/link/ABCDEFGHIJ?state=xyz&code=SplxlOBeZQQYbYS6WxSbIA.
    • To successfully redirect the user, you must register the Alexa redirect URLs with your authentication provider. You can find the URLs to register in the Alexa Redirect URLs entry in the Account Linking section on the developer portal and in the redirect_uri parameter of the authorization request URL.
  • Domains – If your log-in page retrieves content from domains other than your authorization URI, you must add all of those domains to the Domain List field in the developer portal, or in the domains array of the Skill Management API (SMAPI) schema. For example, if your authorization URI, https://www.ridehailer.com/login, pulls in any content (such as images) from domains other than www.ridehailer.com, you need to add them to the domain list. Otherwise, the log-in page will encounter an error.

If you do not have your own authorization server, you can use Login with Amazon (LWA) or any OAuth 2.0 provider that has a certificate signed by an Amazon-approved certificate authority. Note that you cannot use https://letsencrypt.org/, even though it is on the certificate list.

Access token URI requirements

After the Alexa app has gotten an authorization code from the authorization URI, it calls your access token URI to exchange the authorization code for an access token that it can use to access the user's data in your system.

The access token URI must meet the following requirements:

  • Protocol – It must be accessible over HTTPS on port 443.
  • Functionality – The access token URI must:
    • Generate an access token that uniquely identifies the user in your system.
    • Respond to the access token request within 4.5 seconds.
    • Generate a refresh token that the Alexa service can use to get a new access token when the previous one expires, without disrupting the user.
  • Access tokens – The following requirements apply to access tokens:
    • Access tokens must have a lifetime of at least 6 minutes. This means that the expires_in parameter of your access token response must be greater than or equal to 360.
    • The authorization server should not invalidate or revoke access tokens that have been delivered to the Alexa service before the expires_in parameter of the access token response, unless the intent is to shut down access. There is no mechanism to notify the Alexa service that an access token is now invalid. Invalidating an access token too soon can cause outages in highly distributed and concurrent systems such as the Alexa service.
  • Refresh tokens – The authorization server should not immediately invalidate old refresh tokens when generating a new one. In addition to possibly causing outages, this tends to leave the user in a state from which the only recovery is to disable, enable, and account-link the skill from the Alexa app again. The best practice is either to have refresh tokens that do not expire, or, for refresh tokens that do expire, to keep a certain number of old refresh tokens valid. In that case, only invalidate refresh tokens after the authorization server confirms that the Alexa service successfully received the most recent refresh token and used it to obtain a new access token.
  • Old access token URIs – If you change your OAuth configuration after you publish your skill, be sure to keep your old access token URI in service until you have moved all of your existing users to the new access token URI. This is because when Alexa uses the refresh token to retrieve a new access token for an existing user, Alexa uses the access token URI that was configured at the time the user linked their account. If you change the access token URI later, users who previously linked their account continue to use the old URI for retrieving updated tokens. Those users must unlink and re-link accounts to switch to the new access token URI.

Resource server requirements

The resource server, which is the system that contains your user's data, must have a URI that accepts access tokens.

Last updated: Feb 26, 2021