How Users Experience Account Linking for Alexa Skills

Note: Sign in to the developer console to build or publish your skill.

This topic shows common account linking experiences from a user's perspective, and what happens behind the scenes. The examples use a fictional custom skill, Ride Hailer, that lets users order rides.

For an explanation of account linking concepts, see Account Linking Concepts for Alexa Skills. For the special case of app-to-app account linking, which is not covered here, see Set up App-to-App Account Linking for Your Skill.

How users know if a skill requires account linking
How users experience account linking
Related topics

How users know if a skill requires account linking

By default, users can enable a skill without starting the account linking flow. This configuration makes it easier for users to enable your skill and use the features that do not require authentication. For example, Ride Hailer might let users ask how long it will take to get to a particular destination even if they haven't linked their account. Alternatively, you can require users to link their account when they enable the skill.

The skill detail page in the Alexa app indicates whether account linking is required or optional, as follows:

Alexa skill account linking required or optional.

How users experience account linking

The following are three common starting points at which users enter the account linking flow in the Alexa app:

When enabling the skill – The user chooses the ENABLE TO USE button on the skill's detail page in the Alexa app.
From the skill settings – The user goes to the skill settings page in the Alexa app after enabling the skill.
From a skill card – The user tries to use a skill feature that requires authentication, and the skill sends a card to the Alexa app.

The following examples show the user flow for each case, and describe how the Alexa app interacts with the account linking components that you set up.

Note: If your service has an app, users can enter the account linking flow from either the Alexa app or your app. For information about app-to-app account linking, see Set up App-to-App Account Linking for Your Skill.

Initiating account linking when enabling the skill

In the following flow, the user initiates account linking when they enable the skill in the Alexa app.

To enable a skill within the Alexa app, the user chooses the ENABLE TO USE button on the skill detail page. If the skill requires account linking, the user is taken through an account linking flow similar to the following example.

Visual	User experience	Behind the scenes
	The user starts the account linking process by going to the skill detail page and choosing ENABLE TO USE.	The Alexa app opens the skill's authorization URI.
	The user sees Ride Hailer's log-in page and logs in with their Ride Hailer credentials.	Ride Hailer's authorization server, which Alexa accessed using the authorization URI, displays a log-in page within the Alexa app. This page accepts the user's Ride Hailer credentials.
	The user views and accepts any Ride Hailer terms and conditions.	When the user has successfully logged in and accepted any terms and conditions, Ride Hailer's authorization server generates an authorization code to return to Alexa. This authorization code will let Alexa request an access token, which is what it ultimately needs to access the user's Ride Hailer data.
	The user is returned to the Alexa app, and sees a success page.	Ride Hailer's authorization server redirects the user to the Alexa redirect URL, passing the authorization code in the query string. Alexa then opens Ride Hailer's access token URI to get an access token.
	The user says, "Alexa, open Ride Hailer and order a car."	Alexa sends a `LaunchRequest` request to the skill, and includes the access token within the request. The skill extracts the access token from the request, validates the access token, and then uses the access token in a call to Ride Hailer's resource server, which contains the user data. The account linking sample skill on GitHub shows an example of how to extract and use the access token.

Initiating account linking from the skill settings after enabling the skill

In the following flow, the user initiates account linking from the skill settings in the Alexa app after enabling the skill.

After a user enables a skill that supports account linking, the skill detail page in the Alexa app displays a SETTINGS button that the user can access at any time. A user can use this button to link their account if, for example, they enabled the skill by voice or they cancelled out of the account linking flow when they enabled the skill. The following is an example of an account linking flow that begins when the user chooses the SETTINGS button.

Visual	User experience	Behind the scenes
	The user goes to the skill detail page in the Alexa app and chooses SETTINGS.	The Alexa app retrieves the user's account linking settings for the skill.
	The user chooses Link Account.	The Alexa app opens the skill's authorization URI.
	The user sees Ride Hailer's log-in page and logs in with their Ride Hailer credentials.	Ride Hailer's authorization server, which Alexa accessed using the authorization URI, displays a log-in page within the Alexa app. This page accepts the user's Ride Hailer credentials.
	The user views and accepts any Ride Hailer terms and conditions.	When the user has successfully logged in and accepted any terms and conditions, Ride Hailer's authorization server generates an authorization code to return to Alexa. This authorization code will let Alexa request an access token, which is what it ultimately needs to access the user's Ride Hailer data.
	The user is returned to the Alexa app, and sees a success page.	Ride Hailer's authorization server redirects the user to the Alexa redirect URL, passing the authorization code in the query string. Alexa then opens Ride Hailer's access token URI to get an access token.
	The user says, "Alexa, open Ride Hailer and order a car."	Alexa sends a `LaunchRequest` request to the skill, and includes the access token within the request. The skill extracts the access token from the request, validates the access token, and then uses the access token in a call to Ride Hailer's resource server, which contains the user data. The account linking sample skill on GitHub shows an example of how to extract and use the access token.

Initiating account linking from a skill card

In this flow, the user initiates account linking from a card that the skill sends to the Alexa app when the user tries to use a feature that requires authentication. Alexa asks the user if they want to link accounts by using the following speech.

Welcome to {Skill_name}! To reach this functionality, you will need to link your Amazon and {Skill_name} accounts. Check out the instructions I sent to the Alexa app.

Bienvenue sur {Skill_name}! Pour accéder à cette fonctionnalité, vous devrez lier vos comptes Amazon et {Skill_name}. Veuillez consulter les instructions que j'ai envoyées à l'application Alexa.

Willkommen bei {Skill_name}! Um diese Funktion nutzen zu können, müssen dein Amazon-Konto und {Skill_name} Konto verknüpft sein. Sehe dir die Anweisungen an, die ich an die Alexa-App geschickt habe.

{Skill_name} में आपका स्वागत है! इस कार्यक्षमता तक पहुँचने के लिए, आपको अपने Amazon और {Skill_name} खातों को जोड़ना होगा। मेरे द्वारा Alexa ऐप को भेजे गए निर्देशों को देखें।

Benvenuto in {Skill_name}! Per accedere a questa funzionalità, dovrai collegare i tuoi account Amazon e {Skill_name}. Controlla le istruzioni che ho inviato all'app Alexa.

<スキル名＞へようこそ！この機能を利用するには、Amazonアカウントと<スキル名＞アカウントをリンクする必要があります。Alexaアプリに送った手順を確認してください。

Bem-vindo à {Skill_name}! Para acessar esta funcionalidade, você precisará vincular suas contas Amazon e {Skill_name}. Confira as instruções que enviei para o aplicativo Alexa.

¡Bienvenido a {Skill_name}! Para acceder a esta funcionalidad, deberás vincular tus cuentas de Amazon y {Skill_name}. Mira las instrucciones que envié a la aplicación Alexa.

The following example shows the flow that happens behind the scenes.

After a user enables and runs the skill, the skill can send an account linking card to the Alexa app when a user who hasn't linked their account tries to use a feature that requires account linking. The following is an example of an account linking flow that begins when the user enables the skill using their voice.

Visual	User experience	Behind the scenes
	The user says, "Alexa, enable Ride Hailer."	Alexa sends a `LaunchRequest` request to the skill. The request does not include an access token.
	Alexa (through the skill) says, "Welcome to Ride Hailer! To reach this functionality, you will need to link your Amazon and Ride Hailer accounts. Check out the instructions I sent to the Alexa app."	The skill attempts to extract an access token from the request, but there is none. When the skill responds to Alexa, it includes text-to-speech and a Link Account card.
	Alexa displays the Link Account card, and the user chooses LINK ACCOUNT.	The Alexa app opens the skill's authorization URI.
	The user sees Ride Hailer's log-in page and logs in with their Ride Hailer credentials.	Ride Hailer's authorization server, which Alexa accessed using the authorization URI, displays a log-in page within the Alexa app. This page accepts the user's Ride Hailer credentials.
	The user views and accepts any Ride Hailer terms and conditions.	When the user has successfully logged in and accepted any terms and conditions, Ride Hailer's authorization server generates an authorization code to return to Alexa. This authorization code will let Alexa request an access token, which is what it ultimately needs to access the user's Ride Hailer data.
	The user is returned to the Alexa app, and sees a success page.	Ride Hailer's authorization server redirects the user to the Alexa redirect URL, passing the authorization code in the query string. Alexa then opens Ride Hailer's access token URI to get an access token.
	The user says, "Alexa, open Ride Hailer and order a car."	Alexa sends a `LaunchRequest` request to the skill, and includes the access token within the request. The skill extracts the access token from the request, validates the access token, and then uses the access token in a call to Ride Hailer's resource server, which contains the user data. The account linking sample skill on GitHub shows an example of how to extract and use the access token.

Last updated: Apr 11, 2023