Understand Account Linking for Alexa Skills

Account linking enables your skill to connect the skill user's Amazon identity with their identity in a different system.

For example, suppose you own a web-based service, Ride Hailer, that lets users order taxis. You could create a custom skill that enables a user to say, "Alexa, ask Ride Hailer to order a taxi." Completing this request requires the skill to access your Ride Hailer service as a specific Ride Hailer user for profile and payment information. Therefore, you need a link between the Amazon account that is used with the Alexa device and the Ride Hailer account for the user.

This topic describes which skill types require account linking, explains how users experience the account linking flow, and shows where to go for information about how to implement account linking in your skill.

Does my skill need account linking?

For some skill types, account linking is required. For others, it is optional or not supported. For more information, find your skill type in the following list.

  • Account linking is required:
    • Smart home  
    • Video              
    • Meetings        
    • Education       
  • Account linking is optional:
    • Custom           
    • Music              
  • Account linking is not supported for skills that are based on skill types (such as flash briefing) not listed previously.

Choosing an account linking flow

The user experience during account linking falls into one of two types of flows. The primary account linking flow that you implement depends on the experience you want your users to have, and whether you have an app or website:

  • Alexa-app only – This is the most common flow. In this flow, the user accomplishes account linking entirely within the Alexa app. From the Alexa app, the user enables your skill, initiates account linking (or automatically begins the process, for skill types such as smart home), and then enters their username and password for your service. Because this is the most common flow, the majority of this technical documentation focuses on it. For step-by-step images and what happens behind the scenes, see How Users Experience Account Linking for Alexa Skills.
    Alexa app-only account linking.
  • App-to-app – There are two app-to-app account linking flows you can implement:
    • Starting from your app – In this flow, the user starts from your app or website, chooses to initiate account linking, and is then redirected to the Alexa app (or Login with Amazon, if the Alexa app is not installed). The user acknowledges the account linking request within the Alexa app (or Login with Amazon), and is then redirected back to your app or website, which completes account linking and enables the skill by using APIs provided by Alexa. For details about this flow, see App-to-App Account Linking (Starting From Your App).
    • Starting from the Alexa app – In this flow, the user starts the process from within the Alexa app by enabling the skill or by clicking on the Link your account option on your skill's detail page. If the user has your app installed on their device, the device launches your app and asks the user to acknowledge the account linking request. After the user acknowledges the request, the device returns the user to the Alexa app. If the user doesn't have your app installed on their device, the flow is the same as the Alexa-app only account linking flow. That is, the user's browser opens your authorization page, which asks the user to acknowledge the account linking request. After the user acknowledges the request, the authorization website returns the user to the Alexa app. For details about this flow, see App-to-App Account Linking (Starting From the Alexa App).

In any case, after account linking is successful, requests and directives sent to your skill include an access token that your system can use to identify the user. For more information, see Account Linking Concepts for Alexa Skills.