Understand Account Linking

Account linking enables your skill to connect the user's identity with their identity in a different system. This topic describes how you can use account linking with different skill models.

For information about the authorization framework that account linking uses, see How Account Linking Works. To get started with your implementation, see Steps to Implement Account Linking in Your Skill.

Skill models that support account linking

The following skill models support account linking:

  • Custom model – For custom skills, use account linking if your skill needs personalized data from another 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 used with the Alexa device and the Ride Hailer account for the user.
  • Smart home model – Account linking connects the user with your device cloud so that your skill can control the user's devices. For example, if a user has a smart bulb registered with your service, your smart home skill could enable them to say "Alexa, dim the bathroom light". All smart home skills must use account linking.
  • Video model – Account linking connects the user with your device cloud or video service so that the skill can control the user's video devices and play their video content. All video skills must use account linking.
  • Music model – Account linking connects the user with an identity in your music cloud or music service so that the skill can provide content accordingly. For example, some content might be available only to users with a paid account. Some music skills support account linking and some do not.
  • Baby activity model – Account linking connects the user with an identity in your own app or website so that the skill can provide content and save data accordingly. All baby activity skills must use account linking.
  • Meetings model – Account linking gives the user access to your room-booking service. The Alexa-enabled device is registered to an Amazon account, and the Amazon account is linked to a user account in your room-booking service. By linking the accounts, people in your organization can use the meetings skill to reserve rooms, because the linked user account in your room-booking service has access to make reservations. All meetings skills must use account linking.

Other models, such as flash briefing, do not support account linking.

How users experience account linking

There are two types of account linking. 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, and the method to implement if you don't have an app or website. In this flow, the user accomplishes account linking entirely within the Alexa app. From the Alexa app, the user enables your skill, chooses to initiate account linking, 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.
  • App-to-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. If you have an app or website, we encourage you to implement app-to-app account linking in addition to the Alexa app-only flow. For more information, see App-to-App Account Linking.

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 How Account Linking Works.

Is account linking required to enable the skill?

The account linking flow and configuration is similar for all skill models that support account linking. The main differences are whether account linking is required to enable the skill, and the type of authorization grant that you can use. The following table explains which skills require account linking to enable.

Skill model Enabling the skill

Custom model

Users can enable the skill without linking their account. The skill can provide both functionality that requires authentication and functionality that does not.

Smart home model
Video model
Meetings model

Users cannot enable the skill without linking their account.

Music model

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.

Baby activity

Users cannot enable the skill without linking their account.

Other resources: