Requirements for Account Linking for Alexa Skills

Account linking for Alexa skills uses the OAuth 2.0 authentication framework. If your skill uses account linking, your authorization server must adhere to the following requirements.

If you don't 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 can't use https://letsencrypt.org/, even though it's on the certificate list.

To see which skill types require account linking, see Does my skill need account linking?

Authentication framework requirements

Your system must meet the following requirements:

Authorization URI requirements

When the user initiates account linking in the Alexa app, the Alexa service redirects the user to your authorization URI. This URI is the entry point to your authorization server that performs the following functionality:

  1. Displays a log-in page for the user to sign in to your system.
  2. Authenticates the user in your system.
  3. Generates an authorization code that identifies the user.
  4. Returns the authorization code to the Alexa service.

Your authorization URI must meet the following requirements:

  • Protocol – The URI must be accessible over HTTPS on port 443.
  • User interface – The URI must provide a mobile-friendly log-in page that displays within the Alexa app. The log-in page must not 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 the domains to the Domain List field in the developer portal, or in the domains array of the account-linking 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 must add the domains to the domain list. Otherwise, the log-in page will encounter an error.

Token URI requirements

After the Alexa service receives an authorization code from the authorization URI, it calls your access token URI to exchange the authorization code for an access and refresh token to access the user's data in your system.

The access token URI must meet the following requirements:

  • Protocol – The URI must be accessible over HTTPS on port 443.
  • Functionality – The 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.
    • Return the HTTP status codes defined by OAuth 2.0 Error Response.
    • Return invalid_grant only when you intend to break the link between your service and Alexa. Receipt of this error triggers Alexa to delete the customer tokens and unlink their account with your service.
    • Return the correct HTTP status code for server errors, such as HTTP 500 Server Error or other 5XX status codes. Don't send expired or invalid credential status codes for server errors.
  • Access and refresh tokens – The following requirements apply to access and refresh tokens:
    • Amazon recommends that you set the access token time-to-live (TTL) value to at least one hour. Similarly, set the expires_in parameter in the access token response to at least 3600 seconds.
    • Amazon recommends that you set the refresh token TTL value to at least 180 days or to never expire.
    • Access tokens must have a shorter expiration time than refresh tokens.
    • If you enable refresh token rotation, issue a new refresh token, or extend the existing refresh token, every time the authorization server renews the access token.
    • Don't invalidate or revoke access tokens before the expires_in parameter value expires, unless you intend to shut down access. There's no mechanism to notify the Alexa service when an authorization server invalidates an access token. Invalidating an access token too soon can cause outages in highly distributed and concurrent systems, such as the Alexa service.
    • Configure the authorization server to keep old access and refresh tokens valid for a period of time after generating new tokens. Don't invalidate access or refresh tokens until the authorization server confirms that the Alexa service successfully received a new access token along with the most recent refresh token.
    • If your authorization server invalidates refresh tokens due to inactivity, Amazon recommends that you set the TTL for inactivity to one year.
    • Customers might access their account in your system from multiple channels. Don't limit the number of services or clients that your customers can account-link with your system.
    • Don't invalidate tokens during software or hardware maintenance.
  • 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 your existing users to the new access token URI. During token refresh 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.

Was this page helpful?

Last updated: Sep 10, 2024