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:

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

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.
Do you really need account linking?

Account linking is needed when the skill needs to connect with a system that requires authentication. If your skill just needs to keep track of a user to save attributes between sessions, you can use the userId provided in each request to identify the user. The userId for a given user is generated when the user enables your skill in the Alexa app. Every subsequent request from that user to your skill contains the same userId unless the user disables the skill.

Persisting attributes between skill sessions is built in to the ASK SDKs for Node.js, Java, and Python. For details, see ASK SDK documentation about managing attributes.

For a sample skill that illustrates persisting user attributes, see High Low Game.

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

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:

Enabling a skill. Note that the skill card indicates that account linking is required.
Enabling a skill. Note that the skill card indicates that account linking is required.

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:

The skill detail card if the user did not successfully complete linking the accounts.
The skill detail card if the user did not successfully complete linking the accounts.

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:

The link account card in the Alexa app.
A link account card in the Alexa app.

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.

Login page displayed in the Alexa app (Login with Amazon in this example)
Login page displayed in the Alexa app (Login with Amazon in this example)
Success message once the user's account has been linked
Success message once the user's account has been linked

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:

User: Alexa, tell Ride Hailer to get me a ride to work. (The IntentRequest sent to the skill includes a valid access token identifying the user in the Ride Hailer service. Skill retrieves the user's account details and default location.)

Ride Hailer: Ordering a ride using your Ride Hailer account. You wanted to go to your default work location, right?
User: Yes.

Interaction between the user and the skill continues…

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.

User: Alexa, tell Ride Hailer to get me a ride to work. (The IntentRequest sent to the skill does not include a valid access token since the user has not yet linked their account. The skill now needs to request this with a link account card.)

Ride Hailer: Before I can order you rides, you need to log in with your Ride Hailer account. Please visit the Alexa app to link your Ride Hailer account. (This response includes the LinkAccountCard that the user can use to initiate the account linking process.)
Skill interaction ends.

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: Alexa, ask Ride Hailer what services are available in Dallas.

This sends the RideHailerAvailabilityByCity intent. This intent gets public data from the Ride Hailer service and does not need to access the user's Ride Hailer account. Therefore, the skill does not check for the presence of the access token, but just delivers the response.
Ride Hailer: Ride Hailer offers a full range of services in Dallas. You can…
Skill interaction continues…

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:

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:

For the OAuth spec for these grant types, see:

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:

  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.


Was this page helpful?

Last updated: Nov 15, 2023