Understand Account Linking

In your skill, account linking lets you connect the identity of the user with a user account in a different system.

Account Linking and the Skill Model

The following skill models support account linking:

  • Custom model
  • Smart home pre-built model
  • Video pre-built model
  • Music pre-build model

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

For a skill with a custom model, you would use account linking if your skill needs personalized data from another system. For example, suppose you own a web-based service "Car Fu" that lets users order taxis. A custom skill that lets users access Car Fu by voice would be very useful. For example, "Alexa, ask Car Fu to order a taxi." Completing this request requires the skill to access your Car Fu service as a specific Car Fu user for profile and payment information. Therefore, you need a link between the Amazon account used with the Alexa device and the Car Fu account for the user.

For a skill with a pre-built smart home model, account linking connects the user with your device cloud so that your skill can control the user's devices. Account linking is required for smart home skills.

For a skill with a pre-built 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. Account linking is required for video skills.

For a skill with a pre-built 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. Account linking is not required for music skills.

For all skill models, the user completes an account linking flow in the Alexa app to log in to your service. Once the user is authenticated, requests and directives sent to your skill include an access token that your system can use to identify the user.

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 for the particular skill model and the type of authorization grant you can use.

Skill model Enabling the skill Authorizing users

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.

Can use either authorization code grant or implicit grant to authorize the user and obtain an access token.

Smart home model
Video model

Users cannot enable the skill without linking their account.

Must use authorization code grant to authorize the user and obtain an access token.

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.

Must use authorization code grant to authorize the user and obtain an access token.

For implementation guidance, see the steps to implement account linking in your skill section.

OAuth Roles and the Alexa Skills Kit

Account linking in the Alexa Skills Kit uses OAuth 2.0, so some understanding of OAuth 2.0 terms and flows is helpful.

OAuth 2.0 specifies four roles: resource owner, resource server, client, and authorization server. The following table defines the roles and shows how the roles work in the context of the Alexa Skills Kit.

Role OAuth Definition Role within a Custom Skill

Resource owner

The individual who can grant permission to access a protected resource in the resource server.

The Alexa user who wants to connect your skill with their user account in your system and access a protected resource in that system.

For a custom skill that lets users order rides ("Car Fu"), this is the user who wants to enable the Car Fu skill and link it to their Car Fu account so that they can request rides.

Resource server

The server hosting the resources the user wants to access.

In the Car Fu example, the resource server might be a database containing profiles for Car Fu users. The protected resource is the user's Car Fu account profile with their payment information, stored in this database.

Client

The application making the requests to the resource server on behalf of the resource owner, with the resource owner's authorization.

The skill. The skill uses the access token to request information from the resource server.

Note that although the skill is the OAuth client, Alexa performs some operations on behalf of the skill. For example, Alexa makes the requests to the authorization server to get the access token. The skill is still considered the client since it is the only component that ever accesses the protected resources in the resource server.

In the Car Fu example, the Car Fu skill communicates with the resource server to retrieve the user’s Car Fu account profile with their payment information, so that the skill can order the user a ride.

Authorization server

The server that authenticates the identity of the resource owner and issues access tokens. This can be the same as the resource server, but it does not have to be.

In the Car Fu example, the authorization server authenticates the user and provides an access token identifying the user as a valid Car Fu user. The token can then be used to retrieve the user's Car Fu account information from the resource server.

Role OAuth Definition Role within a Smart Home Skill

Resource owner

The individual who can grant permission to access a protected resource in the resource server.

The Alexa user who wants to connect your smart home skill with their user account in the device cloud.

For a skill that can control lighting ("My Lights"), this is the user who wants to enable your skill and link it to their My Lights account so that they can control their My Lights devices with Alexa.

Resource server

The server hosting the resources the user wants to access.

In the My Lights example, this is the cloud-based My Lights service that can control light switches in a user's home. The protected resource is the user's My Lights account, with information about the user's smart devices that the service controls.

Client

The application making the requests to the resource server on behalf of the resource owner, with the resource owner's authorization.

The skill. The skill uses the access token to request information from the resource server.

Note that although the skill is the OAuth client, Alexa performs some operations on behalf of the skill. For example, Alexa makes the requests to the authorization server to get the access token. The skill is still considered the client since it is the only component that ever accesses the protected resources in the resource server.

In the My Lights example, the My Lights skill communicates with the resource server to retrieve information about the user's lights that it can then use to turn a light on or off.

Authorization server

The server that authenticates the identity of the resource owner and issues access tokens. This can be the same as the resource server, but it does not have to be.

In the My Lights example, this server authenticates the user and provides an access token identifying the user as a valid My Lights user.

Who Owns the Resource Server and Authorization Server?

The resource server and authorization server do not need to be owned by the same person or company. Some of the common scenarios include:

Scenario What this means Example

You own both the resource server and the authorization server.

You built your own the authorization server for your service.

You built the Car Fu service. As part of this service, you built both the resource server that stores Car Fu profiles, and the authorization server that issues tokens granting access to the user profiles in the Car Fu system.

You own the resource server, but not the authorization server.

You use a third-party authorization server such as Login with Amazon. The authorization server provides you with data you can map to your users in your resource server.

You own the Car Fu service, but you did not build an authorization server. Your resource server contains profile data for your users. You use Login with Amazon to authenticate users, and then use the Amazon profile:user_id to access a user's profile in your Car Fu database. .

You own neither the resource server nor the authorization server.

Your are connecting to a third-party API that requires user authentication.

You don't own Car Fu, but Car Fu exposes a public API that supports OAuth 2.0. You build an unofficial Car Fu skill that connects to the public API, authenticates the user, and makes an API call to order a car ride.

For any scenario in which you do not own or did not build all of the components, consult the third-party documentation for the third-party service to determine:

Steps to Implement Account Linking in Your Skill

  1. Review how account linking works with your skill model:

  2. Configure account linking in the developer console in the Build > Account Linking section. For details, see one the following:

  3. Update your code to retrieve the access token and authenticate the user. See one of the following:

  4. Once your skill is live, you can see account linking metrics (such as the total number of account linking initiations) on the Measure > Skill Activation page in the developer console.

OAuth Resources:

Other Resources: