The most common problems with setting up account linking for your smart home Alexa Skill — and simple tips to solve them
A wide variety of smart home developers leverage account linking to drive improvements to the customer experience for their Alexa Skills. Account linking enables customers to connect their Amazon identity (account with which they login to the Alexa or Amazon app) to an identity in a different system. For smart home and Internet of Things (IoT) device makers, implementing account linking on Alexa skills facilitates voice control integration, improves user experiences through personalization, and simplified setup. When account linking is implemented correctly, it allows for seamless integration between Alexa and third-party systems, enabling customers to enjoy a smooth and personalized experience. However, if account linking is not handled properly, it can lead to a broken connection between Alexa and your services and that can negatively impact the overall quality of the Alexa experience. To implement account linking, Alexa uses the OAuth 2.0 authentication framework (official specification). Once the accounts are linked and your skill is enabled, your authorization server (defined in the OAuth 2.0 framework) will have already provided a pair of tokens to Alexa (click here to understand the detailed flow). Alexa will include these tokens as authorization parameters in the request sent to your skill, thus enabling your skill to identify the user and complete the request accordingly. Token management such as storing, re-issuing, and revoking tokens is critical for skill operation with Alexa. Failure to handle these tokens correctly such as prematurely invalidating access and refreshing tokens can lead to authentication failures, resulting in critical functionality breakdowns and frustrating user experiences. For example consider the frustration caused by an expired access token when a customer is unable to turn on their lights post issuing the voice command multiple times or by using the Alexa app. The best practices outlined below will help you get ahead of the most commonly known issues related to account linking and token management: 1) Token Expiration: The authorization server issues a set of access and refresh tokens. Both of these tokens have a designated expiration time, specified by the expires_in parameter. The lifespan of the access token is shorter as compared to the refresh token. Once the access tokens have expired, the refresh token is used to get a new access token. 1.1) Short token expiration duration Solution: A longer time-to-live (TTL) (a.k.a. expires_in) value gives more time for your customers to use your skill without requiring them to re-link their account. We recommend setting the access token TTL value to at least one hour, and the refresh token TTL value to at least 180 days or to never expire.
1.2) Authorization server prematurely invalidates the access or refresh token. Solution: Do not invalidate the tokens before the designated expiration time unless you want to terminate access for a particular user or application. Please ensure even if your authorization server has issued the new access and refresh token, the previously issued access token stays valid until the expires_in time has elapsed. 1.3) Refresh token expired due to inactivity Solution: Configuring the refresh token expiry due to inactivity to a very small interval may lead to frequent account de-linking, and may lead to poor customer experience. If the refresh token expiry due to inactivity is enabled, please configure the inactivity duration to at least one year.
