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.
Note: 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.
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.
Enabling the skill – Users cannot enable a smart home skill without linking their account.
Example – You have a service that enables users to register and control smart bulbs through your app. In addition to your app, you want users to be able to control their registered smart bulbs by speaking to Alexa, so you create a smart home skill. When users go to the Alexa app to enable your skill, they follow the instructions to log into your app and link their account. Then, for example, they can say "Alexa, dim the bathroom light", which uses the dim settings they configured in your service.
Enabling the skill – Users cannot enable a video skill without linking their account.
Example – You are a cloud-enabled video provider. You have a service that enables users to purchase and play video content. You now want users to be able to control their video devices and play their purchased videos by asking Alexa, so you create a video skill. To set up the skill, the user enables your video skill in the Alexa app, and follows the instructions to log into your app and link their account. Then, for example, they can say "Alexa, resume [device]" to resume watching content on the specified device.
Enabling the skill – Users cannot enable a meetings skill without linking their account.
Example – Your organization has a room-booking service that enables users to find and book conference rooms in your building. You want users to be able to book rooms by voice, so you create a meetings skill. When users go to the Alexa app to enable your skill, they follow the instructions to log into their room-booking account. After successful linking, they can say (for example) "Alexa, find a room for half an hour."
Enabling the skill – Users cannot enable an education skill without linking their account.
Example – You are an education tech provider that maintains student information such as grades, coursework, or school communications in a classroom management app. Your users already have a username and password to log in to the app. You want your users to be able to retrieve their student information by asking Alexa questions such as "Alexa, what do I have due tomorrow?"
Enabling the skill – Users can enable the skill without linking their account. The skill can provide both functionality that requires authentication and functionality that does not.
Example – 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 used with the Alexa device and the Ride Hailer account for the user.
Enabling the skill –Some music skills support account linking and some do not. For music skills that support account linking, users cannot enable the skill without linking their account.
Example – You are a cloud-enabled music service provider who enables users to purchase and play audio content using an app. You now want users to be able to access your service and stream that content through an Alexa-enabled device, so you create a music skill. To set up the skill, the user enables your music skill in the Alexa app, and follows the instructions to log into your app and link their account. Then, for example, the user can say "Alexa, play [favorite artist] on [skill name]." Some music skills support account linking and some do not. For example, some content might be available to all users, and other content only to users with a paid account.
Enabling the skill – Users can enable the skill without linking their account. The skill can provide two types of functionality, one that requires account linking and one that does not. Account linking is required before the skill recites any Personal Health Information (PHI) data.
Example – You own a primary care clinic service, Care for All, that operates clinics around a metropolitan area. You are thinking about creating a custom skill to help serve your clients.
You skill includes functionality that does not require account linking
Your custom skill lets a user ask, "Alexa, where is the nearest Care for All clinic?" This request doesn't require your skill to access your Care for All service as a specific Care for All user. It does not pull any profile information and does not recite any PHI data. Therefore, account linking is not required before the skill completes this request.
You skill includes functionality that requires account linking
However, let's pretend your skill allows a user to ask, "Alexa, when is my next Care for All appointment?" This request needs to recite personalized information. It requires your skill to access your Care for All service as a specific Care for All user. It pulls profile information and might recite PHI data. Therefore, account linking is required before the skill completes this request.
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.
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.
