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.
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:
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 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.
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 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.
In the following 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.
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 order a ride, 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 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.
