Add Account Linking to Your Alexa Skill


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.

This documentation pertains to account linking between one user in your system and the Amazon account to which the Alexa device is registered. For more advanced personalization, your skill can let users link multiple voice profiles within a single Amazon account or household to their individual accounts in your system. For more information, see Personalization and Account Linking.

Does my skill need account linking?

For some skill types, account linking is required. For others, account linking is optional or not supported. The following list provides examples of skill types where account linking is required or optional. Some skills, such as flash briefing skills, don't support account linking at all.

  • Account linking is required:
    • Smart home       
    • Video                  
  • Account linking is optional:
    • Custom               
    • Music                  
    • HIPAA-Eligible   

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.


Was this page helpful?

Last updated: Nov 15, 2023