Voice-Forward Account Linking Flow for Alexa Skills (LWA OAuth)

If your Alexa skill requires account linking, you can implement your skill such that recognized Alexa customers can use their voice to link their Amazon account with the account they have with your service. When a customer's request requires account linking, Alexa asks for the customer's consent, authenticates their request with a one-time password, and then links the accounts. The customer doesn't have to go to the Alexa app to complete the account linking steps.

In the following example, the customer links their Amazon account to their Ride Hailer account by using their voice.

Customer: Alexa, open Ride Hailer.
Alexa: Here's the skill Ride Hailer by Ride Hailer Inc.
Alexa (skill): Welcome to Ride Hailer! Would you like to link your account so I can help you book your rides? You can say, 'Link my account', or 'No'.
Customer: Link my account.
Alexa: To link your account, I'll need to share some information from your Alexa profile.
Alexa: Do you give Ride Hailer permission to access your name and email address? You can say, 'I approve', or 'No'.
Customer: I approve.
Alexa: Annie, to authenticate your request, say, 'My code is', followed by the code we sent to your phone.
Customer: Alexa, my code is 1-2-3-4-5-6.
Alexa: Great, Annie. I've signed you in with Ride Hailer using Login with Amazon. You can manage your linked account by going to the skills section of your Alexa app.
Alexa (skill): Now, I can help you book a ride! Where would you like to go?

For a walkthrough of how to implement voice-forward account linking, see Tutorial: Implement Voice-Forward Account Linking in Your Skill.

Terminology

Before you implement voice-forward account linking, review the following terms:

  • Login with Amazon (LWA) – An authentication system, based on OAuth 2.0, that enables customers to log in and grant access to their customer profile data. If you onboard your site to LWA, customers can log in to your site or app by using their Amazon account. For general information about LWA, see the Login with Amazon documentation. For the LWA SDKs, see Login with Amazon SDKs.
  • Skill connections – An Alexa feature that enables a skill to use another skill or service to perform a specific task. For details, see Understand Skill Connections.
  • Voice-Forward Account Linking skill – The Amazon-owned Alexa skill that interacts with the customer during the voice-forward account linking flow, and then passes control to your skill through skill connections when the linking process is complete.
  • Your service – The service that you provide. In the previous example, the web-based service, "Ride Hailer," lets customers order taxis.
  • Your skill – The Alexa skill that enables users to interact with your service by using Alexa. This documentation assumes that you're the skill developer.

Prerequisites

To implement voice-forward account linking, your skill and service must meet certain requirements. To use voice-forward account linking, the customer must also meet certain requirements.

Skill and website requirements

To implement voice-forward account linking, your skill must meet the following requirements:

  • Your skill must be a custom skill. For details about custom skills, see Understand Custom Skills.
  • Your skill must support account linking with the authorization code grant type. For details about account linking, see Add Account Linking to Your Alexa Skill.
  • Your service must use LWA for customer authentication. For details about LWA, see Login with Amazon.
  • Your skill must enable permissions for the customer information your skill requires. Supported permissions include the customer name, phone number, email address, and country and postal code. To capture the name for customers who are new to your skill, you must, at a minimum, enable either Full Name or Given Name permissions in the developer console. For details about how to configure permissions, see Request Customer Contact Information for Use in Your Skill.
  • Your skill must not support personalization. That is, TOOLS > Permissions > Skills Personalization must be disabled in the developer console.

Customer requirements

For voice-forward account linking to be available to a particular customer, the customer must meet the following requirements:

  • The customer must have a voice profile in the Alexa app. For details, see Manage skill personalization as a user.
  • The customer must specify their phone number in their voice profile.
  • The customer must be the owner of the Amazon account to which the device is registered.

User experience for voice-forward account linking

The following examples show the user experience when the customer consents or declines to link their accounts by using their voice, as well as when voice-forward account linking isn't available.

Customer consents to link their account

In the following example flow, the customer consents to link their Amazon account to their Ride Hailer account by using their voice.

Customer declines to share their profile information

In the following example flow, the customer doesn't consent to sharing their profile information. As a result, account linking falls back to the Alexa app method.

Customer doesn't answer

In the following example flow, the customer doesn't answer the question as to whether they allow Alexa to link their accounts. As a result, account linking falls back to the Alexa app method.

Alexa doesn't recognize the customer

In the following example flow, voice-forward account linking isn't an option because Alexa doesn't recognize the customer. As a result, account linking falls back to the Alexa app method.

Customer is not eligible

In the following example flow, voice-forward account linking isn't an option because the customer doesn't own the Amazon account to which the device is registered. As a result, account linking falls back to the Alexa app method.

Customer doesn't have a phone number in their profile

In the following example flow, the voice-forward account linking flow exits because the customer doesn't have a phone number in their profile. The phone number is necessary for one-time password validation. As a result, account linking falls back to the Alexa app method.

Customer granted permission in the past

In the following example flow, the voice-forward account linking flow isn't needed because the customer granted permission in the past.

Customer denied a linking request in the recent past

In the following example flow, the voice-forward account linking flow exits because the customer recently declined a linking request for this skill.

Flow for voice-forward account linking (LWA OAuth)

From a back-end perspective, voice-forward account linking involves the following steps.

  1. Your skill determines when to initiate the voice-forward account linking experience.
  2. Your skill initiates voice-forward account linking and Alexa asks for the customer's consent.
  3. Alexa completes the account linking flow, notifies the customer, and passes control back to your skill.

Step 1: Your skill determines when to initiate the voice-forward account linking experience

In this step, Alexa launches your skill. While interacting with the customer, your skill determines when account linking is needed.

  1. Alexa launches your skill.
  2. The customer makes a request that needs account linking.
  3. Your skill checks whether the customer is already account-linked. That is, your skill checks if a token is available in the accessToken property of the user object, which is available in the context object. You should initiate the voice-forward account linking flow only if the access token for the customer is not present in the user object.
  4. If the results of the previous step are that you want to initiate the voice-forward account linking flow, your skill explains to the customer the benefit of linking their accounts. To help provide a seamless transition into the voice-forward account linking experience, you can repurpose the following example to explain to your customer the value of linking their account: "By the way, you can request rides from your Ride Hailer account by linking your account. Would you like to link it so I can help you book your rides? You can say, 'Link my account', or 'No'."
  5. If the customer says, "Link my account", your skill uses skill connections to send a Connections.StartConnection directive for initiating the voice-forward account linking flow. For details, see Implement a handler to request the task to initiate voice-forward account linking.

Step 2: Your skill initiates voice-forward account linking and Alexa asks for the customer's consent

If the result of step 1 indicates that Alexa should perform the voice-forward account linking flow, the next step is for Alexa to request and store the customer's consent.

  1. Alexa checks if the customer has enabled personalization in their Alexa app settings and is the owner of the Amazon account to which device is registered. For a list of these required settings, see Customer Requirements. If the user hasn't enabled personalization or isn't the owner of the Amazon account, voice-forward account linking exits, and then Alexa returns control to the skill. For details about how users enable personalization, see Manage skill personalization as a user.
  2. Alexa determines whether to start the voice-forward account linking flow by verifying that all of the following conditions are true:
    • Your skill isn't already linked by the customer.
    • The skill manifest of your skill specifies that your skill supports account linking in general, and voice-forward account linking in particular.
    • The customer granted access to all of the configured permission scopes.
  3. If a customer hasn't granted access to all of the configured permission scopes and hasn't denied account linking in the recent past, the voice-forward account linking skill seeks permission for the permission scopes that are not consented. If a customer denies giving consent, Alexa explains that the customer can link their accounts by using the Alexa app, and then passes control back to your skill.

Assuming that the previous steps were successful, Alexa links the accounts, reports the linking outcome to the customer, and then passes control back to your skill.

  1. The voice-forward account linking skill calls LWA to request an authorization code for the customer in your system.
  2. The voice-forward account linking skill calls LWA to exchange the authorization code for an access token and refresh token.
  3. Depending on whether account linking succeeded or failed, Alexa notifies the customer of the outcome.
    • Example success message: "Great, [person's first name]. I've signed you in with [skill name] using Login with Amazon. You can manage your linked account by going to the skills section of your Alexa app."
    • Example error message: "Sorry, something went wrong. To link your account with [skill name], go to the skills section of your Alexa app."
  4. Alexa then resumes the skill session and sends your skill a response on the status of account linking in the form of a Tasks.CompleteTask directive. For details, see Implement a handler to get the response on the task to initiate voice-forward account linking.

For a walkthrough of how to implement voice-forward account linking, see Tutorial: Implement Voice-Forward Account Linking in Your Skill.

Flow diagram

The following diagram shows what happens behind the scenes during the voice-forward account linking flow. To see the details, click the diagram, and then zoom in.

Voice-forward consent flow.

Was this page helpful?

Last updated: Nov 15, 2023