Account Linking for Custom Skills

---

Some custom skills require the ability to connect the identity of the user with a user in another system. This is referred to as account linking, since the goal is to create a link between the Alexa user and the user account in your system.

This document provides an overview of account linking specifically for custom skills. If you want to skip straight to the details, see:

• Configure an Authorization Code Grant
• Configure an Implicit Grant
• Validate and Use Access Tokens in Custom Skill Code

If you are working with a skill of a different type, such as smart home or video, see Account Linking for Smart Home and Other Domains.

• When to use account linking
• How users link their accounts
  • Start from the skill detail card
  • Start from a link account card
  • User completes the account linking process
  • User interacts with the skill
  • User disables a skill
• Authorization code grant type for custom skills
• Steps to implement account linking in a custom skill
• Related topics

When to use account linking

Use account linking in a custom skill if you need to connect the user's Alexa account with an account in another system and retrieve personalized information from that other system. For example:

• Connect a skill to a service you run.
• Connect a skill to a third party service that supports OAuth 2.0.

How users link their accounts

Users can start account linking in one of two ways:

• From the skill detail card in the Alexa app while enabling the skill
• From a link account card in the Alexa app after making a request that requires authentication.

This gives users flexibility – if the user skips the account linking step when enabling the skill, they can come back to it later, after making a request that requires the authentication.

You can also enable users to initiate account linking from within your app. For more information, see App-to-App Account Linking.

Your custom skill can also make account linking optional. For instance, you could provide basic functionality that does not require authentication, and then more advanced functionality that does require it. When you configure your skill in this way, the user does not see the account linking flow when they enable the skill. For more about this option, see Let Users Enable Your Skill without Account Linking.

In both of these cases, you can determine whether the user has linked their account by the presence of the access token (accessToken) in the request to your skill. See Get the Access Token from the Request.

• Start from the Skill Detail Card
• Start from a Link Account Card
• User Completes the Account Linking Process

Start from the skill detail card

If your skill requires account linking, the skill detail card notes that account linking is required. When the user clicks Enable, the Alexa app automatically starts the account linking process:

If the user cancels the account linking process, the skill is still enabled, but the skill card includes a Settings button so the user can go back and link their account later:

Start from a link account card

This flow is possible if the user skips the account linking process when they enable the skill or if they enable the skill by voice instead of with the Alexa app. Users can skip the account linking flow when enabling the skill if you select the option to let users enable it without account linking.

After the user makes a request that requires authentication, your skill returns a link account card (LinkAccount) directing the user to connect their accounts. As noted previously, you can determine that the user's account is not linked by checking for the presence of the access token (accessToken) in the request to your skill. See Get the Access Token from the Request.

The user can then start the process from this card:

User completes the account linking process

Regardless of how the user starts the process, the remaining steps are the same:

1. Once the user starts the process, the app displays a login page for the other service.
2. The user provides their credentials in the login page and authenticates with the service.
3. The user is redirected back to a "success" page within the Alexa app and the skill is ready to use.

If the account linking was successful, Alexa now stores an access token (provided by the other system) that identifies the user in the other system. This token is now included in all requests to the skill, so the skill can access the user's information in the other system when needed.

In this example, this skill uses Login with Amazon, so the user sees an Amazon login page within the Alexa app.

User interacts with the skill

Users can invoke the skill and make requests normally. If the user's account has been successfully linked, the requests include the access token. The skill uses the token to access information in the other system.

For example, in the following interaction, the Ride Hailer skill uses the token to get the user's profile, which has payment information and a default "work" location:

If the user's account has not been linked yet, the request does not include the access token. The skill can check for this and return both:

• Speech text that briefly explains the benefits of linking accounts.
• A link account card that the user can use to link their account in the Alexa app.

Your skill can have requests that do not need personalized data from your system and therefore do not require authentication. For these intents, your skill can send back a normal response and let the user continue interacting with the skill without account linking:

User disables a skill

If the user disables the skill in the Alexa app, the Alexa service deletes the access token associated with that user and skill. This removes the link between the user's Alexa account and their account in your service.

If the user later re-enables the skill, they will need to initiate the account linking process again to create a new link between their Alexa account and their account with your service.

Authorization code grant type for custom skills

The Alexa Skills Kit supports two OAuth authorization grant types for custom skills:

• Authorization code grant type
• Implicit grant type

The primary difference between these two types is in how the access token is obtained from the authorization server.

• In an implicit grant, the authentication server returns the access token after the user logs in during the account linking process.
• In an authorization code grant, the authentication server returns an authorization code after the user logs in during the account linking process. Alexa then uses this code to request an access token / refresh token pair from the authorization server. Alexa can then use the refresh token to request a new access token / refresh token pair after the old token expires.

While the implicit grant type is sometimes easier to implement, the authorization code grant type is the more secure, robust solution and it should be used if possible. The implicit grant type can be an option if your authorization server does not support the authorization code grant type. Note that if you use the implicit grant type, and the token ever expires, the user must re-link their accounts in the Alexa app, which can cause a poor user experience.

For details about how you configure the authorization grant type for your skill, see the following:

• Configure an Implicit Grant
• Configure an Authorization Code Grant

For the OAuth spec for these grant types, see:

• Implicit Grant
• Authorization Code Grant

Steps to implement account linking in a custom skill

To add account linking to your custom skill, you do the following:

1. Decide whether to use an implicit grant or an authorization code grant as your grant type.

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

   • Configure an Implicit Grant
   • Configure an Authorization Code Grant

3. Add account linking logic to the service for your skill. Your skill code needs to check for the access token on incoming requests and take appropriate actions.

   For details, see Validate and Use Access Tokens in Custom Skill Code.

Related topics

• Validate and Use Access Tokens in Custom Skill Code
• Quick Reference: Add Account Linking to an Alexa Skill
• Add Account Linking to Your Alexa Skill
• Account Linking Concepts for Alexa Skills

---

---

Last updated: Sep 10, 2024