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.

2) Refresh Token Rotation
Refresh tokens are typically long-lived and in some cases they never expire. Refresh token rotation is a technique, typically used for single page applications (SPAs), to issue a new pair of access and refresh token every time the access token is refreshed. Once the token is refreshed, if the old refresh token is reused, the authorization servers detect it as a reuse, and to safeguard the resource server, it invalidates all of the tokens issued by the server.

2.1) Due to networking delays, a reuse of the older refresh token leads to revoked access, and disables account linking

Solution: Most authorization servers provide a grace period for which the older refresh token can be used without leading to reuse detection and token revocation. When using refresh token rotation, it’s recommended to configure the grace period to a minimum of 30 seconds.

3) Authorization Server Migration
Organizational or infrastructure changes often require OAuth server migration. Migrating the OAuth server would lead to updated authorization and access token url and new client credentials. Developers can update the skill to use the updated authorization server parameters.

3.1) Unable to refresh access tokens after authorization server migration or client credentials update.

Solution: The updated authorization server parameters or client credentials will only be used for new account linking. Alexa will continue to use the existing credentials to refresh the access tokens for all of the previously linked accounts. As a result, it’s critical to maintain the previously provided authorization server URIs and credentials. 

4) Error Handling
If the request cannot be successfully processed, the authorization server responds with an error response which includes an error code and error description (defined by the OAuth 2.0 specification). The error codes are processed by Alexa and depending on the error it may lead to account de-linking.

4.1) Customers’ account automatically getting de-linked

Solution: In the event of authorization server downtime or the authorization server not being able to process the refresh request, a proper error response such as 5xx status code or "SERVER_ERROR" should be returned. Responding with error types such as "INVALID_GRANT" or "EXPIRED_AUTHORIZATION_CREDENTIAL" can be interpreted as the response to deliberately revoke the tokens, leading to the unlinking of the associated customer's account.

5) Alexa Token Management
For some use cases such as sending proactive events or requesting user data, Alexa provides tokens to developers which they can use to send proactive updates or request user data. The lack of these tokens do not lead to account de-linking but impacts the customer experience.

5.1) Low PSU quality due to improper token handling

Solution: Low PSU quality can be associated with multiple reasons such as not sending proactive state updates when the device state changes. One of the reasons associated with poor state quality is developers losing the PSU tokens or not storing them at all. At the time of skill enablement, Alexa sends an AccessGrant directive with an authorization code. The skill should use this authorization code to retrieve access and refresh tokens and respond with a success response, at which point the skill gets enabled and accounts get linked. Your skill must save these tokens in a persistent storage to ensure it can access them later to send PSUs to Alexa. If your skill was already enabled by some customers before you enabled this skill permission, we can help with the backfill process. Please reach out to your contact at Amazon, if you do not have one then please reach out via the contact us page on the developer console. 

For more information please refer to the Alexa developer documentation for account linking here.