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, including 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.

How users know if a skill requires account linking

If your skill requires account linking to fulfill any user request, users see Account linking required below the Enable to Use or Launch button in the Alexa app. If account linking is optional for your skill (that is, users can enable your skill and use the features that don't require authentication), users see Account linking available below the Enable to Use or Launch button.

The following images show how the skill detail page in the Alexa app indicates whether account linking is required or optional.

Alexa skill account linking required or optional.

Factors that influence how users experience account linking

How users experience account linking depends on a combination of the following factors:

Where the user starts the account linking process – The starting point can be the Alexa app (for example, when enabling or launching the skill from the skill detail page), your service's app (Ride Hailer, in this fictional example), the screen of an Alexa-enabled device with a screen when users make a request that requires account linking, or by voice when a user's request to your skill requires their account to be linked and your skill implements voice-forward account linking.
Whether your app supports app-to-app account linking (starting from the Alexa app) – In this flow, the user starts the process from the Alexa app. The Alexa app sends the user to your app or opens your authorization URI in an in-app browser tab where users can enter their credentials with your service, if your app isn't installed. From there, the user consents to the account-linking request and is sent back to Alexa app to complete account linking.
Whether your app supports app-to-app account linking (starting from your app) – In this flow, the user starts the process from your app, which sends the user to the Alexa app. In the Alexa app, the user acknowledges the account-linking request. The Alexa app redirects the user back to your app, which enables the skill and completes account linking by calling the account linking APIs that Alexa provides. If the user doesn't have the Alexa app installed, this flow falls back to the Login with Amazon (LWA) flow, where users can enter their Amazon credentials.

Account-linking flow examples

The following sections provide examples of the different account-linking flows organized by where the user starts:

When starting from the Alexa app
When starting from your app
When prompted by an Alexa-enabled device with a screen
- From a QR code on an Alexa-enabled device with a screen
- With credentials on an Alexa-enabled device with a screen
When prompted by voice

When starting from the Alexa app

This section contains flows in which the user taps on the account linking link from somewhere in the Alexa app, such as when enabling the skill, from the skill settings, from a skill card, or from a push notification.

When enabling or launching the skill from the skill detail page (with app-to-app account linking)

In the following flow, the user initiates account linking when they enable the skill in the Alexa app. The user has your app installed on their device and your skill implements app-to-app account linking (starting from the Alexa app), so the device launches your app and asks the user to acknowledge the account-linking request. After the user authorizes the request in your app, they're sent to the Alexa app, and their account gets linked.

Visual	User Experience	Behind the Scenes
Alexa app	The user starts the account linking process by going to the skill detail page and choosing ENABLE TO USE or LAUNCH.	The Alexa app opens your app and makes an authorization request to your app by using the `authorizationUrlsByPlatform` that you define when you configure app-to-app account linking (starting from the Alexa app).
Ride Hailer app	Within the Ride Hailer app, the user sees a consent screen that asks them to accept or deny the request to link their account. The user authorizes the request and accepts any Ride Hailer terms and conditions.	When the user has logged in and accepted any terms and conditions, Ride Hailer's authorization server generates an authorization code to return to Alexa. This authorization code lets Alexa request an access token, which is what Alexa needs to access the user's Ride Hailer data.
Alexa app	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, thereby completing the account linking process.
	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.

When enabling or launching the skill from the skill detail page (without app-to-app account linking)

In the following flow, the user initiates account linking when they enable the skill in the Alexa app. The skill doesn't implement app-to-app account linking (starting from the Alexa app) or the user doesn't have your app installed on their device, so the user completes the account linking process within the Alexa app by entering their credentials on your authorization URI.

Visual	User Experience	Behind the Scenes
Alexa app	The user starts the account linking process by going to the skill detail page and choosing ENABLE TO USE or LAUNCH.	The Alexa app opens the skill's authorization URI.
Ride Hailer authorization page opened within the Alexa app	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.
Ride Hailer authorization page opened within the Alexa app	The user views and accepts any Ride Hailer terms and conditions.	When the user has logged in and accepted any terms and conditions, Ride Hailer's authorization server generates an authorization code to return to Alexa. This authorization code lets Alexa request an access token, which Alexa needs to access the user's Ride Hailer data.
Alexa app	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, thereby completing the account linking process.
	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.

From the skill settings after enabling the skill

After a user enables a custom skill or a music 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 canceled out of the account-linking flow when they enabled the skill. The following example shows an account-linking flow that begins when the user chooses the SETTINGS button.

Note: The following example assumes that your skill implements app-to-app account linking (starting from the Alexa app) and that the user has installed your app on their device. If not, your users must also enter their credentials on your authorization URI before they can link their account.

Visual	User Experience	Behind the Scenes
Alexa app	The user goes to the skill detail page in the Alexa app and chooses SETTINGS.	The Alexa app retrieves the user's settings for the skill.
Alexa app	The user chooses Link Account.	The Alexa app opens your app and makes an authorization request to your app by using the `authorizationUrlsByPlatform` that you define when you configure app-to-app account linking (starting from the Alexa app).
Ride Hailer app	Within the Ride Hailer app, the user sees a consent screen that asks them to accept or deny the request to link their account. The user authorizes the request and accepts any Ride Hailer terms and conditions.	When the user has authorized and accepted any terms and conditions, Ride Hailer's authorization server generates an authorization code to return to Alexa. This authorization code lets Alexa request an access token, which Alexa needs to access the user's Ride Hailer data.
Alexa app	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, thereby completing the account linking process.
	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.

From a skill card

In the following flow, the user initiates account linking from an account linking card that the skill sends to the Alexa app when the user tries to use a feature that requires authentication.

Visual	User Experience	Behind the Scenes
	The user says, "Alexa, enable Ride Hailer."	Alexa sends a `LaunchRequest` request to the skill. The request doesn't 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, the skill includes text-to-speech and a Link Account card.
Alexa app	Alexa displays the Link Account card, and the user chooses Link Ride Hailer account.	The Alexa app opens your app and makes an authorization request to your app by using the `authorizationUrlsByPlatform` that you define when you configure app-to-app account linking (starting from the Alexa app).
Ride Hailer app	Within the Ride Hailer app, the user sees a consent screen that asks them to accept or deny the request to link their account. The user authorizes the request and accepts any Ride Hailer terms and conditions.	When the user has authorized and accepted any terms and conditions, Ride Hailer's authorization server generates an authorization code to return to Alexa. This authorization code lets Alexa request an access token, which Alexa needs to access the user's Ride Hailer data.
Alexa app	The user is returned to the Alexa app and sees a success page.	Ride Hailer's app redirects the user to the Alexa app redirect URL, passing the authorization code in the query string. Alexa then opens Ride Hailer's access token URI to get an access token, thereby completing the linking process.
	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.

From a push notification

In the following flow, the user initiates account linking from a push notification that's sent when the skill publishes an account linking card. An account linking card is a card that your skill sends to the Alexa app when the user tries to use a feature that requires authentication.

Note: This feature is available for custom skills and music skills only.

Visual	User Experience	Behind the Scenes
	The user says, "Alexa, enable Ride Hailer."	Alexa sends a `LaunchRequest` request to your skill. The request doesn't 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, the skill includes text-to-speech and a Link Account card. This triggers an account linking push notification.
	The user taps the push notification from the Alexa app, which requests that they link their Ride Hailer account.	The Alexa app opens your app and makes an authorization request to your app by using the `authorizationUrlsByPlatform` that you define when you configure app-to-app account linking (starting from the Alexa app).
Ride Hailer app	The Alexa app opens briefly, and then the Alexa app opens the Ride Hailer app. Within the Ride Hailer app, the user sees a consent screen that asks them to accept or deny the request to link their account. The user authorizes the request and accepts any Ride Hailer terms and conditions.	When the user has authorized and accepted any terms and conditions, Ride Hailer's authorization server generates an authorization code to return to Alexa. This authorization code lets Alexa request an access token, which Alexa needs to access the user's Ride Hailer data.
Alexa app	The user is returned to the Alexa app and sees a success page.	Ride Hailer's app redirects the user to the Alexa app redirect URL, passing the authorization code in the query string. Alexa then opens Ride Hailer's access token URI to get an access token, thereby completing the linking process.
	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.

When starting from your app

If your skill implements app-to-app account linking (starting from your app), the user taps on the account linking link in your app and is sent to the Alexa app, if the Alexa app is installed. The user then authorizes the request by tapping the Link button, and is then sent to your app as account linked.

Visual	User Experience	Behind the Scenes
Ride Hailer app	Your app gives the user the option to enable your skill and link their account with Alexa. The user chooses to link their account with Alexa.	You can offer account linking to users in multiple places. For tips, see Best practices.
Alexa app	The user is taken to the Alexa app, where they tap Link.	Your app redirects the user to the Alexa app by using a Universal Link (iOS) or App Link (Android).
Ride Hailer app	The user is returned to your app and sees their status as linked along with a success message.	The Alexa app redirects the user to your app along with their Amazon authorization code, which you can use to complete the account linking process.
	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 following flow shows how, if the Alexa app isn't installed, the user sees an LWA page on which they log in to link their account.

Visual	User Experience	Behind the Scenes
Ride Hailer app	Your app gives the user the option to enable your skill and link their account with Alexa. The user chooses to link their account with Alexa.	You can offer account linking to users in multiple places. For tips, see Best practices.
Login with Amazon	The user sees a Login with Amazon page, where they log in.	Your app launches Login with Amazon (LWA) using the LWA fallback URL in an in-app browser tab.
Login with Amazon	The user sees an LWA consent screen, where they authorize access for Ride Hailer.	LWA gets consent from the user to generate their authorization code.
Ride Hailer app	The user is returned to your app, and sees their status as linked along with a success message.	LWA sends the user back to your app using your redirect URLs, and sends the user's Amazon authorization code as a part of that redirect. You can use this code to complete the account linking process.
	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.

When prompted by an Alexa-enabled device with a screen

Note: This feature is available for custom skills only.

When the skill receives a request that requires account linking, the Alexa-enabled device with a screen shows the user a QR code on the screen. The user scans the code. Alternatively, the user can enter their credentials.

From a QR code on an Alexa-enabled device with a screen

In the following flow, the Alexa-enabled device with a screen shows the user an account-linking QR code when they try to use a feature that requires authentication.

Visual	User Experience	Behind the Scenes
	The user says, "Alexa, enable Ride Hailer."	Alexa determines that the user's account isn't linked with the Ride Hailer skill.
Alexa-enabled device with a screen	Alexa says, "To use Ride Hailer, you need to link your account. Scan the QR code on the screen with your phone." The user scans the QR code.	The Alexa-enabled device with a screen displays a QR code. Scanning the QR code deep-links the user in the Alexa app and starts the linking flow, which opens Ride Hailer's app.
Ride Hailer app	The Alexa app opens briefly, and then the Alexa app opens the Ride Hailer app. Within the Ride Hailer app, the user sees a consent screen that asks them to accept or deny the request to link their account. The user authorizes the request and accepts any Ride Hailer terms and conditions.	When the user has authorized and accepted any terms and conditions, Ride Hailer's authorization server generates an authorization code to return to Alexa. This authorization code lets Alexa request an access token, which Alexa needs to access the user's Ride Hailer data.
Alexa app	The user is returned to the Alexa app and sees a success page.	Ride Hailer's app redirects the user to the Alexa app redirect URL, passing the authorization code in the query string. Alexa then opens Ride Hailer's access token URI to get an access token, thereby completing the account-linking process.
Alexa-enabled device with a screen	The Alexa-enabled device with a screen shows the user a success message.	As soon as the user completes the account-linking flow in the app, the Alexa-enabled device with a screen refreshes to show a success message. The skill experience launches shortly afterward. 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.

With credentials on an Alexa-enabled device with a screen

In the following flow, the user enters their credentials on their Alexa-enabled device with a screen when they try to use a feature that requires authentication.

Visual	User Experience	Behind the Scenes
	The user says, "Alexa, enable Ride Hailer."	Alexa determines that the user's account isn't linked with the Ride Hailer skill.
Alexa-enabled device with a screen	Alexa says, "To use Ride Hailer, you need to link your account. Scan the QR code on the screen with your phone." and presents an alternative account-linking method with a button called Sign in using this device. The user taps the button.	When the user taps the button, Alexa starts the account-linking flow on the Alexa-enabled device with a screen.
Alexa-enabled device with a screen	If your skills supports personal account linking, the user can select their profile on the screen. Otherwise, the profile-picker screen is skipped.	Alexa displays a list of profiles from the user's Amazon account. Alexa uses this selection to link the Ride Hailer account to the selected profile after the user completes account linking.
Alexa-enabled device with a screen	The user sees Ride Hailer's log-in page in the browser of their Alexa-enabled device with a screen 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.
Alexa-enabled device with a screen	The user views and accepts any Ride Hailer terms and conditions.	When the user has logged in and accepted any terms and conditions, Ride Hailer's authorization server generates an authorization code to return to Alexa. This authorization code lets Alexa request an access token, which is what Alexa needs to access the user's Ride Hailer data.
Alexa-enabled device with a screen	The Alexa-enabled device with a screen shows the user a success message.	As soon as the user completes the account-linking flow on their Alexa-enabled device with a screen, they see a success page. The skill experience launches shortly afterward. 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.

When prompted by voice

When the skill receives a request that requires account linking, the skill takes the user through the voice-forward account linking (LWA OAuth) flow.