Troubleshooting Common Account Linking Issues with Alexa Skills

You can use account linking to connect a user's Amazon account to the account that they have with your service. For more information on how this works, see How Users Experience Account Linking for Alexa Skills.

This blog is a guide for developers who have just started implementing account linking, and addresses issues you might encounter during the development process, including how to troubleshoot the “We were unable to link <skill name> at this time” error, what happens when account linking expires after certain time, and what to do if account linking does not work on certain devices.

For the authorization code grant account linking flow, one of the most common issues is account linking failing during the process of exchanging the authorization token for the access and refresh token. When a user starts the account linking process, the Alexa app displays a login page, which uses the authorization URI from the account linking configuration in the Alexa Developer Console. After your authorization server authenticates the user, the authorization server will generate an authorization code. The Alexa service then uses the authorization code in a POST request to retrieve an access and refresh token pair from your authorization server's access token URI. If Alexa cannot receive the access and refresh token pair from your authorization server, it will display the error below.

Here are some areas to check on your authorization server:

• Check that the authorization server is generating a valid authorization code for exchange of access and refresh tokens.
• Log the response from your authorization server to make sure it returns the access token and refresh token in a JSON response to Alexa. Make sure it is not sending an error or an invalid JSON response to Alexa.

If you are using a third party OAuth server (such as Google Sign-In or Facebook Login) and do not have access to the services’ logs, you can set up AWS API gateway to get access to additional logs. Check out the tutorial on how to set up Amazon API Gateway as a proxy in order to check the JSON that is being sent to and from the Alexa service.

For smart home skills, you may have turned on "Send Alexa Events" permissions to send events, such as change report events, to proactively report device states. 

If the "Send Alexa Events" permissions is on for your smart home skill, you need to handle the AcceptGrant directive that is sent to your skill’s Lambda function during account linking. Your skill endpoint has to respond synchronously with an AcceptGrant.Response in order to retrieve the authorization code that is used to proactively report states.

To test whether this is the cause of the account linking failure, try turning off the "Send Alexa Events" permissions from Alexa Developer Console and then testing account linking. If account linking now works, then make sure your Lambda function can handle the AcceptGrant directive.

This indicates that Alexa was unable to use the provided refresh token to retrieve a new access and refresh token pair. Access tokens must have a lifetime of at least 6 minutes. Set access tokens with a lifetime of greater than or equal to 6 minutes or 360 seconds in the expires_in parameter. Additionally, make sure that the “Default Access Token Expiration Time” on Alexa Developer Console is also greater than or equal to 360 seconds.
Example access token response:

Sometimes account linking may work on one device, but not on another. For example, while it may work on web browsers, it might not work on the Alexa app. This could be due to certain domains missing from the “Domain List” in the account linking configuration in the Alexa Developer Console.

If your skill’s authorization server pulls in any content from domains other than your authorization URI's domain, you will need to add those domains to your skill's configuration. You can add these under the Developer Console > Account Linking > Domain List section for your skill.

Make sure you have added all external domains the account linking page calls or uses. This needs to include all domains to which you're making external calls. For example, if you make a call to oauth.sample.com, simply adding sample.com isn't adequate - you need to add oauth.sample.com.

This usually indicates there is something wrong with the redirect_uri, or that the redirect URL is invalid. Alternatively, if the request size is too large (this includes the length of the redirect URI, combined with all the cookies for the domain), this can stop the page from redirecting correctly.

Testing in an incognito or private window and confirming that account linking succeeds would also indicate this issue. If account linking can be completed in an incognito or private window, try reducing the length of the redirect URL. As the redirect URL includes all of the query parameters, reducing the length of these parameters can alleviate the problem. A common reason where redirects fail is due to authorization codes being too long - reducing the length of authorization codes may resolve this issue.

This blog has outlined how to troubleshoot four of the most common account linking issues. If your issue is not listed here, please check out the forum on account linking.