App-to-App Account Linking (Starting From the Alexa App)

This account linking flow enables users to link their Alexa user identity with their identity in another service by starting from the Alexa app. Users can link their account without entering their account credentials in either your app or the Alexa app, when they are logged in to both apps on their mobile device.

Your other options for implementing the account linking flow are the following:

If you have an app or website and can obtain an authorization grant for your user without requiring them to log in again, we encourage you to implement one of the app-to-app account linking flows in addition to the Alexa app-only flow.

For the rest of this topic, the term app-to-app account linking refers specifically to app-to-app account linking that starts from the Alexa app.

Terminology

This topic uses the following terms:

  • Service – The service that you provide. For example, you might have a web-based service, "Ride Hailer", that lets users order taxis.
  • App – The app that your users use to interact with your service. Continuing the previous example, you might have a "Ride Hailer" app. This discussion assumes that you are the developer of the app.
  • Skill – The Alexa skill that enables the user to interact with your service using Alexa. This discussion assumes that you are the developer of the skill.
  • Alexa app – The Amazon Alexa app that users can download for their mobile device.
  • OAuth 2.0 – An authentication standard by which your service can allow Alexa, with the user's permission, to access information from the account that the user has set up with you. For the OAuth 2.0 standard, see OAuth 2.0.
  • App Link – A deep link on Android that a user clicks to launch an app. For details about App Links, see the Android documentation.
  • Universal Link – A deep link on iOS that a user clicks to launch an app. For details about Universal Links, see the iOS documentation.

User experience

During app-to-app account linking, the user goes through the following workflow:

  • The user starts the process from within the Alexa app by enabling the skill or by clicking on the Link your account option on your skill's detail page. If the user starts the account linking process, one of two things happens depending on whether the user has your app installed on their mobile device.
  • (App flow) If the user has your app installed on their device, the device launches your app and asks the user to acknowledge the account linking request. After the user acknowledges the request, the device returns the user to the Alexa app.
  • (Browser flow) If the user doesn't have your app installed on their device, the flow is the same as the Alexa-app only account linking flow. That is, the user's browser opens your authorization page, which asks the user to acknowledge the account linking request. After the user acknowledges the request, the authorization website returns the user to the Alexa app.

After the account is linked and the user is using your skill, the skill uses the same workflow as Alexa-app only account linking. In any case, disabling the skill causes the accounts to unlink.

Your app is installed

The following is an example of the flow when your app is installed.

Alexa app-to-app account linking.

Your app isn't installed

The following is an example of the flow when your app isn't installed. This flow is the same as the Alexa-app-only flow (browser flow).

Alexa account linking browser flow.

Which flow to implement

The app-to-app account linking flow that you implement depends on whether you expect your users to have your app installed on their mobile device. If the user has your app installed on their device, implement the app flow as the primary flow, and the browser flow as the fallback when your app isn't installed. If you don't expect your users to have your app on their mobile device, implement the browser flow.

How it works

App-to-app account linking works by using OAuth 2.0. The steps are as follows:

  1. The user installs the Alexa app and logs in.
  2. The user starts the account linking process in the Alexa app by doing one of the following:
    1. Tapping Enable in your skill's detail page.
    2. Tapping Link Account in your skill's settings page, if the user previously enabled your skill.
    3. Tapping Link Account in the account linking card that appeared in the user's Alexa app when they interacted with your skill.
  3. What happens next depends on whether your app is installed on the user's device.
    • If your app is installed:
      1. The Alexa app sends the user to your app by using your app's Universal Link (iOS) or App Link (Android) with the parameters necessary for an authorization request.
      2. Your app displays a consent screen that asks the user to accept or deny the request to link their account.
      3. The user acknowledges the request.
      4. (Optional) Your app obtains additional information, such as a preferred store location, from the user.
      5. Your app sends the user back to the Alexa app with the authorization response.
    • If your app isn't installed: This is the Alexa-app only account linking experience described in Choosing an account linking flow.
  4. The Alexa app sends the authorization response from the previous step to the Alexa service, which finishes linking the accounts. The Alexa service uses the following process, depending on whether your skill uses an implicit grant or an authorization code grant.
    • Implicit grant (custom skills only): The Alexa service stores the access token that the previous step provided.
    • Authorization code grant: The Alexa service calls your token server to exchange the authorization code from the previous step for an access/refresh token pair, and then stores the access/refresh token pair.
  5. The account linking process is complete.

Parameters for the authorization request to your app

This section describes the parameters of the authorization request that the Alexa service makes to your app by using the Universal Link (iOS) or App Link (Android) that you provide.

Field Description

client_id

An identifier for your skill. You can use this to provide any skill-specific functionality, such as distinguishing between different skills you have configured with account linking. You define the client_id when you configure account linking for your skill.

authorizationUrlsByPlatform

A URL that the Alexa service uses to open your app for app-to-app account linking. The URL that the Alexa service uses depends on the user's device type: App Link (Android) or Universal Link (iOS).

redirect_uri

The Alexa app URI that your app redirects the user to with the authorization response. The redirect URI is the same redirect_uri that the Alexa-app only account linking flow uses. You must whitelist these URIs with your authorization server. These URIs are Universal Link / App Link-enabled.

For the authorization code grant type, the redirect URI is one of the following values: https://pitangui.amazon.com/api/skill/link/{Your Amazon Vendor ID} https://layla.amazon.com/api/skill/link/{Your Amazon Vendor ID} https://alexa.amazon.co.jp/api/skill/link/{Your Amazon Vendor ID}

For the implicit grant type, the redirect URI is one of the following values: https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId={Your Amazon Vendor ID} https://layla.amazon.com/spa/skill/account-linking-status.html?vendorId={Your Amazon Vendor ID} https://alexa.amazon.co.jp/spa/skill/account-linking-status.html?vendorId={Your Amazon Vendor ID}

For further details, see Alexa Redirect URLs.

scope

An optional list of scopes that indicate the access that the Alexa user needs. You define these scopes when you configure account linking for your skill.

  • Your service can use this information when it generates the access token. For example, your service might create a token that allows access to basic profile information but doesn't allow access to payment information.
  • You can use multiple scopes. The scope list is delimited by URL-encoded spaces.
  • The log-in page should tell users what access they are allowing by linking their accounts.

response_type

The type of response that the request returns after your service authenticates the user. Set to code for the authorization code grant type or token for the implicit grant type.

state

A value that the Alexa service uses to track the user through the account linking process.

The Alexa app sends a state value to your authorization server by using the authorization URI. Your authorization server must use that same state value when it subsequently calls the redirect URI for that particular account linking request. Each request to the authorization server has its own state value.

Key steps

This section describes key steps, and provides code examples for an iOS app (10.0 or higher) and an Android app by using the following libraries and languages:

The following figure provides an overview of the steps. Descriptions of the steps, including code examples, follow.

Alexa app-to-App account linking steps

Jump to step: 1  2  3  4  5

Step 1: Enable Universal Links (iOS) or App Links (Android) for your app

To enable the Alexa app to request authorization from your app, you must enable Universal Links (iOS) or App Links (Android).

Step 2: Configure the skill for account linking

You configure your skill by using the developer console, the Alexa Skills Kit Command Line Interface (ASK CLI), or the Alexa Skill Management API (SMAPI). During this configuration, you specify aspects like your app's authorization URL (deep-link enabled), access token URL, and so on.

For details about configuring account linking, see Configure an Authorization Code Grant and Configure an Implicit Grant.

Step 3: Handle the authorization request in your app

When the Alexa service calls your app's Universal Link or App Link using authorizationUrlsByPlatform, your app must show a consent screen to the user and get their authorization to link their account.

Step 4: Redirect the user to the Alexa app

After the user accepts the account linking request in your app, redirect them to the Alexa app to finish the account linking process.

Step 5: Use the access token in the skill

After a user successfully enables your skill and links Alexa with your service, requests sent to your skill include the user's access token. Your skill code needs to get the access token from the request, validate it, and use it to retrieve the necessary user information from your resource server.

Best practices

When you implement app-to-app account linking, keep the following in mind:

  • User interface – When designing your app's user interface, follow the guidelines for Amazon Echo and Alexa brand usage.
  • Security – If the user's request includes a financial transaction or involves personal information, ask the user to answer a previously-defined security question before fulfilling their request.
  • Response URI generation – In your code that redirects the user to the Alexa app with an authorization or access token response, we highly recommend that you build the response URI in your backend. This enables you to quickly change parameters or validation logic without having to rebuild your app.
  • Enabling app-to-app account linking in your app – Before publishing a live version of your skill, ensure that your app can handle your Universal Link (iOS) or App Link (Android) to open your authorization page.

Testing guidelines

In addition to making sure that your skill meets the certification requirements that apply to all skills, test your implementation of app-to-app account linking. Before doing so, make sure that you've installed both your app and the Alexa app on the mobile device and that you're signed in to both apps. Next, enable the skill through the Alexa app and check the following:

  • Upon skill enablement, your app should open to a landing page that provides a confirmation for users to proceed with account linking.
  • After selecting the link in the app, users should be taken back to the Alexa app to confirm that linking is complete.
  • Interact with the skill to ensure that the skill is properly linked.

If you implemented app-to-app account linking for both iOS and Android, test the full experience separately on both.

Frequently asked questions

The following are frequently asked questions about app-to-app account linking.

Q: I have multiple apps that can handle account linking requests. How should I set up the app-to-app account linking flow?

In this scenario, your authorization URIs must be able to open different apps. Universal Linking and App Links support this functionality as follows:

  • iOS – You can add the domain of the authorization URI to the entitlements file of every app that you want to be able to handle the account linking request. In the Apple App Association File of the domain, you can then add a different entry for each app. If a user has more than one of the apps installed, the order of their appearance in the Apple App Association File determines the order of preference.

  • Android – You can add the domain of the authorization URI to the app manifest of every app that you want to be able to handle the account linking request. In the Asset Links JSON of the domain, you can add a different entry for each app. If a user has more than one of the apps installed, the Intent Filter Priority of your app's App Manifest determines the order of preference.

Q: Can I use the same app if I have multiple skills?

Yes. You can do this in either of the following two ways:

  • Use the same authorization URI for every skill that you own.
  • Have separate authorization URIs for every skill, and enable Universal Links or App Links for each skill that can open the app.
Q: What if a user wants to link Alexa with a different user account than the account they are currently logged in to with your app?

If you expect your users to link a different account with Alexa than the one they're signed in with, you can enable users to log out and choose a different account when they receive the request to link accounts in your app.

Q: I use a third-party authorization server. Can I implement app-to-app account linking?

Yes, but only if your authorization server exposes an API that generates authorization codes or access tokens by using a session identifier without having the user to log in again.

Q: Will users be able to do device discovery after linking their accounts?

Yes. The user experience after linking the accounts is the same as in the Alexa-app only flow.

Q: Will users be able to consent to permissions?

Yes. Users will continue to be able to grant skill permissions before linking the accounts.

Q: I set up my skill to work with skill personalization. Will users be able to link their personal accounts?

Yes. The app-to-app account linking flow supports the linking of personal accounts.

Q: How do I know the user's Alexa app supports the app-to-app account linking flow?

The Alexa app will only initiate requests to your app when the user has an Alexa app that can finish the app-to-app account linking flow.

Q: How does a user revoke account linking?

Disabling the skill unlinks the user's account. As with any skill, a user can say, "Alexa, disable <skill name>" or disable the skill from the skill's detail page.

Q: I configured my skill to send Alexa Events. How do Alexa events work with the app-to-app flow?

If you enable the Send Alexa Events permission for the skill, your lambda function must handle the AcceptGrant directive. If your skill doesn't handle this directive, account linking fails when the user attempts to enable your skill. For details, see Authenticate a Customer to Alexa with Permissions.