How Users Experience Account Linking for Alexa Skills


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

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.

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.

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.

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.

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.

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.

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.

When prompted by an Alexa-enabled device with a screen

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.

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.

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.


Was this page helpful?

Last updated: Nov 15, 2023