Troubleshooting Common Account Linking Issues with Alexa Skills

Chihiro Tatara Dec 22, 2020
Training & Tutorials Alexa Skills Kit

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.

Unable to Link the Account  

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.

Alexa App screenshot

Here are some tips on how to troubleshoot this error:

Check Authorization Server Logs

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.

Check AcceptGrant Response

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.

Account Linking Succeeds but the User Has to Link Accounts Again in the Future

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:

Copied to clipboard
HTTP/1.1 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma: no-cache

Test to see if your authorization server can successfully refresh the access token pair and is not invalidating refresh tokens before the 5 minute window of time is up. If your authorization server has already invalidated the refresh token, Alexa will not be able to refresh the access and refresh token pair and your customer will have to link their account from Alexa app again.

Account Linking Does Not Work on Certain Devices

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.

domain image

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, simply adding isn't adequate - you need to add

HTTP 400 Error during Redirect

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. 

Related Articles

Understand Account Linking for Alexa Skills
Access token URI requirements
Send Events to the Event Gateway
Alexa.Authorization Interface
Alexa: Debugging account linking
How to Set up Amazon API Gateway as a Proxy to Debug Account Linking