Getting started with account linking
- For a tutorial on implementing account linking, check out the following link on implementing Login with Amazon:
- If you're looking for account linking best practices, or advice on how to go about implementing account linking from the beginning, take a look at our blog post:
- Some use cases for account linking (such as obtaining customer address) can best be achieved via Customer Permissions. For more information on permissions, take a look at our documentation:
- For Authorization Code Grant flow, see here for steps:
- For tips on troubleshooting App-to-App Account Linking, check out the following guide:
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:
- 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:
- 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:
- 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:
- US - alexa.amazon.com
- UK - alexa.amazon.co.uk
- JP - alexa.amazon.co.jp
- 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.
- 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:
- Check that your server is responding within 4.5 seconds
- When your authorization server is responding to the access token request, your server needs to respond within 4.5 seconds. If it doesn't, the request will timeout and account linking won't succeed. For other requirements for the access token requirements, check out further details here:
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.
- Ensure that the access token time to live (TTL) is more than 5 minutes.
- Ensure that your authorization server can successfully refresh the access/refresh token pair when presented with a refresh token by Alexa.
- 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.
- 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.
- 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 oauth.sample.com, simply adding sample.com isn't adequate - you need to add oauth.sample.com.
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 https://www.google.com/settings/u/1/security 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
- Popups aren't supported. If you try to link with a popup, it won't work.
- 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:
- https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA#state=xyz∾cess_token=2YotnFZFEjr1zCsicxLpAA&token_type=Bearer
- Note that the account linking URL must be a HTTPS URL, with a certificate from an Amazon approved CA authority:
- When sending your response with the access token, make sure you send a 200 OK status code.
- 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 https://tools.ietf.org/html/rfc6749#section-2.3.1.
- 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:
- Skill ID:
- 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
- Customer ID of the account that failed:
- Find your customer ID here: https://developer.amazon.com/mycid.html
- Exact time and date (in UTC, or with time zone) you tried and failed to link the skill
- Region(s) you're trying to link with:
- EU/NA/Asia?
- Device/Type platform:
- Android/iOS/browser
- Version of Alexa app:
- Under Settings -> about the Alexa app
- 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
