Sindy@Amazon avatar image
Sindy@Amazon posted

Alexa Account Linking Debugging Tips

Getting started with account linking

Troubleshooting guide

Problem: "We were unable to link <skill name> at this time." or "Linking unsuccessful"

Solution: These are the most common error encountered when configuring account linking. They are usually resolved through the following steps:

  1. Check your authorization server for logs
    • More often than not, account linking fails due to an error sent by your authorization server. Check the responses from your authorization server to see what you are sending back to Alexa when your authorization server is presented with the authorization code in exchange for an access/refresh token pair.
    • If you don't have access to the service you are account linking with, it would be a good idea at this point to get access to additional logs. A good way to do this is via this excellent guide on setting up AWS API gateway as an intermediary:
  2. For smart home skills, check your AcceptGrant response
    • If you are building a smart home skill and using account linking, you might have the "Send Alexa Events" permissions turned on within the Developer Console for your skill so that you can send events to the Alexa Event Gateway. If so, you need to respond to the AcceptGrant directive that is sent to your skill during account linking. More details here:
  3. Troubleshoot using the Alexa app in your browser
    • When enabling skills on your account, you can use the Alexa app in your browser. The URL of the Alexa app will change depending on the region set in your account. For example:
    • You can test account linking like you would on your mobile Alexa app, but with the addition of developer tools and debuggers on your browser. This will let you view the network requests going back and forth for account linking, and you may notice a parameter or some other issue you may have missed. You especially want to check to make sure the state parameter stays the same throughout the account linking process.
  4. Check that your server is responding within 4.5 seconds

Problem: Account linking succeeds, but after some time the customer has to link accounts again

Solution: This usually indicates that Alexa was unable to use the provided refresh token to grab a new access/refresh token pair.

  1. Ensure that the access token time to live (TTL) is more than 5 minutes.
  2. Ensure that your authorization server can successfully refresh the access/refresh token pair when presented with a refresh token by Alexa.
  3. Ensure that you are not invalidating refresh tokens too early - Alexa may take some time after the access token has expired to refresh the token, and if your authorization server has already invalidated the refresh token, Alexa will not be able to refresh the access/refresh token pair and your customer will have their account linking disabled. More details here:

Problem: Account linking does not work on certain devices (blank screen, new window opened on smartphones)

Solution: This may indicate that that you have failed to add domains from which external content (such as images) is pulled from your log-in page.

  1. If your skill 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 > Tools > Account Linking > Domain List tab for your skill.
  2. Make sure you have all external domains the account linking calls/uses added. This needs to include all domains to which you're making external calls. If you make a call to, simply adding isn't adequate - you need to add

Problem: Issues when account linking with Google

Solution: As a result of Google's OAuth architecture the refresh_token is only provided the first time a user authorizes. If you authorize many times on the same account (for example, while testing) that specific account won't return a refresh_token, so when our service requests one, none is returned. It's also possible you haven't set access_type=offline when making the query from Google, which means you are not requesting the refresh token.

  • To fix any specific account to work with refresh tokens go to and revoke access from your app. Then the next time you authenticate it will treat it as a first time authentication, and the skill should refresh properly again.

Other important tips/requirements

  1. Popups aren't supported. If you try to link with a popup, it won't work.
  2. For skills linking with implicit grants, the query parameters for sensitive information, such as the account linking token and state, should be included as a URL fragment starting with #. It cannot be in a query string. An example format would be as below:
  3. Note that the account linking URL must be a HTTPS URL, with a certificate from an Amazon approved CA authority:
  4. When sending your response with the access token, make sure you send a 200 OK status code.
  5. Amazon supports HTTP basic and credentials in request body as authentication methods. If your service uses another type of authentication, account linking will fail. For more information about client authentication, please read
  6. More specifically, for authentication code type, the access token must be sent in JSON by default as per the OAuth2 spec. If the parameter is in the response as a parameter string by default, account linking will fail.
    • Notably, Github will fail for this reason. Unfortunately, at this time it's impossible to account link with Github without some sort of intermediary API gateway.

If all else fails

If you have followed all of these debugging steps above, either try again at a later time or file a contact us case with the all of following information:

  1. Skill ID:
  2. Account linking test credentials:
    • The account and password for logging into the account linking page - do not provide your Amazon developer nor retail account credentials
  3. Customer ID of the account that failed:
  4. Exact time and date (in UTC, or with time zone) you tried and failed to link the skill
  5. Region(s) you're trying to link with:
    • EU/NA/Asia?
  6. Device/Type platform:
    • Android/iOS/browser
  7. Version of Alexa app:
    • Under Settings -> about the Alexa app
  8. Description/link to screenshot of issue:
    • Empty page?
    • Seeing 'Unable to link' page?
    • Button on page not functioning?

As well as the following account linking configuration from the Account Linking tab on the Developer Console:

  • Authorization Url:
  • Domains List:
  • Account Linking Type:
    • Implicit Grant or Authorization Code Grant
alexa skills kitaccount linkingwhitelist
10 |5000

Up to 2 attachments (including images) can be used with a maximum of 512.0 KiB each and 1.0 MiB total.

AcckiyGerman avatar image AcckiyGerman commented ·

The oAuth2 protocol can vary a lot depending of implementation.

So it would be nice to write few how-to articles, describing creation of an oAuth2 authorization endpoint for Alexa skills, using few of the most popular languages and frameworks with existing oAuth2 plugins e.g.

PHP/Laravell/Yii, Python/Django/Flask, Node/Express.js

P.S. I've implemented an oAuth2 auth server for Alexa using 'django-oauth-toolkit' and the process was not easy and clear at all.

0 Likes 0 ·



jasonk contributed to this article Brian@Amazon contributed to this article petertong contributed to this article hukaiyin contributed to this article nick_gardner contributed to this article wangchao contributed to this article Sindy@Amazon contributed to this article