Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

App-to-App Account Linking

App-to-app account linking enables users to link their Alexa user identity with their identity in another service by starting from your app or website. With app-to-app account linking, your users can:

  • Discover your Alexa skill through your app
  • Initiate skill enablement and account linking from within your app
  • 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
  • Link their account from your app using Login with Amazon (LWA), when the Alexa app is not installed on their mobile device

In other words, app-to-app account linking is another way of setting up the skill and linking the account. After the account is linked and the user is using your skill, the skill uses the same workflow as Alexa-app only account linking. If you have an app or website, we encourage you to implement app-to-app account linking in addition to the Alexa app-only flow.

This topic describes the user experience during app-to-app account linking, how it works, and provides guidance on how to implement it. For general information about account linking in Alexa skills, see Understand Account Linking.

Terminology

In this topic, we use 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. We assume that you are the developer of the app.
  • Skill – The Alexa skill that enables the user to interact with your service using Alexa. We assume that you are the developer of the skill.
  • Alexa app – The Amazon Alexa app that users can download for their mobile device.
  • Login with Amazon (LWA) – An authentication system that enables users to log in and grant access to their user profile data. In terms of app-to-app account linking, LWA is a fallback that you can implement to handle the case in which users do not have the Alexa app installed on their mobile device. For general information about LWA, see the Login with Amazon documentation.

User experience

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

  • Your app gives the user the option to enable your skill and link their account with Alexa. If the user chooses to link their account, one of two things happens, depending on whether the Alexa app is installed on the mobile device.
  • (Alexa app flow) If the Alexa app is installed on the device, the Alexa app launches and asks the user to acknowledge the account linking request. After acknowledging the request, the user is returned to your app.
  • (LWA flow) If the Alexa app is not installed on the device, an in-app browser window with LWA opens, and the user can enter their Amazon credentials or create an Amazon account. The user is then asked to give your skill permission to link the accounts. After acknowledging the request, the user is returned to your app.

In any case, disabling the skill causes the accounts to unlink.

The following are example screenshots. As mentioned previously, the flow depends on whether the user has the Alexa app installed.

Alexa app is installed

The following is an example of the Alexa app flow.

Alexa app-to-app account linking.

Alexa app is not installed

The following is an example of the LWA flow.

Alexa app-to-app account linking using Login With Amazon

Which flow to implement

The Alexa app flow is available for iOS only. As such, the flow that you implement depends on whether you are developing an iOS app, an Android app, or a website:

  • iOS apps – Implement the Alexa app flow as the primary flow, and the LWA flow as a fallback for when the Alexa app is not installed.
  • Websites and Android apps – Implement the LWA flow.

How it works

App-to-app account linking works by using OAuth 2.0. The following figure shows what goes on behind the scenes when the user starts account linking from your app on their mobile device. (Click image to enlarge.)

Alexa app-to-App account linking flow

The steps are as follows. For information about the URLs mentioned, see URLs and endpoints.

  1. The user installs your app on their mobile device, and logs in to your app.
  2. Your app presents the user with the option to enable your skill and link their account with Alexa, with a mention of the benefit (for example, "You can now order a car through Ride Hailer by voice with Alexa"). The user acknowledges the linking request.
  3. What happens next depends on whether the Alexa app is installed on the user's device.
    • If the Alexa app is installed:
      1. Your app launches the Alexa app using the Alexa app URL with the authorization request parameters described later.
      2. The Alexa app launches and asks the user if they want to link Alexa with your service.
      3. The user acknowledges the linking request.
      4. The Alexa app 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.
    • If the Alexa app is not installed:
      1. Your app launches LWA using the LWA fallback URL in an in-app browser tab (not a native browser app) with the authorization request parameters described later.
      2. LWA launches and asks the user to log in to their Amazon account.
      3. LWA asks the user if they want to link Alexa with your service. The user acknowledges the linking request.
      4. 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.
  4. Your backend server calls the LWA authorization service URL and exchanges the Amazon authorization code it retrieved in the previous step for an Amazon access token.
  5. Your backend server calls your authorization server to get the user's authorization code (for their account in your service).
  6. Your backend server calls the Alexa Skill Activation API with the user's Amazon access token and the user's authorization code for your service, to enable the skill and link the account.
  7. Alexa goes to your app's access token URL to exchange the user's authorization code for your service for an access token for your service, thereby completing account linking.

URLs and endpoints

This section describes the URLs and endpoints that relate to app-to-app account linking. A description of the parameters follows.

Name Where it's used Details

Alexa app URL

Your app uses this universal link (iOS) to send the user to the Alexa app to acknowledge the linking request. For parameter descriptions, see Parameters for the Alexa app URL and the LWA fallback URL. For general information about universal linking, see Allowing Apps and Websites to Link to Your Content in Apple's documentation.

You can store the Alexa app URL and the LWA fallback URL in the back end, and retrieve them with a GET request. You can also store the URLs locally to avoid an extra network call; this might require a new build if you modify the skill security profile in the future.

Format: https://alexa.amazon.com/spa/skill-account-linking-consent?fragment=skill-account-linking-consent&client_id={ClientId}&scope=alexa::skills:account_linking&skill_stage={skillStage}&response_type=code&redirect_uri={yourRedirectUrl}&state={yourState}

LWA fallback URL

A link that sends the user to LWA to enter their Amazon credentials. It works for iOS, Android, and websites. Your app uses this if the user doesn't have the Alexa app installed on their device. For parameter descriptions, see Parameters for the Alexa app URL and the LWA fallback URL.

See the previous note for the Alexa app URL about storing the URLs.

Format: https://www.amazon.com/ap/oa?client_id={ClientId}&scope=alexa::skills:account_linking&response_type=code&redirect_uri={yourRedirectUrl}&state={yourState}

Your app's redirect URLs

The Alexa app (or LWA, if the Alexa app is not installed) uses this universal link to send the user back to your app after they acknowledge the linking request in the Alexa app or LWA. The parameters returned with the redirect provide your app with the user's Amazon authorization code, which is valid for 5 minutes.

You specify one or more of these using the developer console, the ASK CLI, or SMAPI. See the required syntax in the URI specification.

Authorization URL

The URL of your authorization server. The authorization server must accept the user's credentials, authenticate the user, and generate an authorization code that the Alexa app can later pass to your authorization server to retrieve an access token that uniquely identifies the user with your service.

This link is only used for regular (not app-to-app) account linking. You specify this using the developer console, the ASK CLI, or SMAPI.

Access token URL

Your token server, which Alexa uses to exchange the user's authorization code (for your service) for an access token, to complete account linking.

You specify this using the developer console, the ASK CLI, or SMAPI.

LWA authorization service

Your backend server uses this to exchange the user's Amazon authorization code for an Amazon access token. This enables your app to call the Alexa service to enable the skill and link the account for the user.

Host: https://api.amazon.com with POST request on /auth/o2/token

Alexa Skill Activation API endpoint

Your backend server calls this to enable the skill for the user. For more information about the Alexa Skill Activation API, see Alexa Skill Activation API.

Format: https://api.amazonalexa.com/v1/users/~current/skills/{yourSkillId}/enablement Depending on where the user is located, the base URL could be https://api.amazonalexa.com, https://api.eu.amazonalexa.com, or https://api.fe.amazonalexa.com.

Parameters for the Alexa app URL and the LWA fallback URL

Field Description

Client ID

The client ID that the developer console provides when you enable app-to-app account linking in the developer console.

Client secret

The client secret that the developer console provides when you enable app-to-app account linking in the developer console.

Redirect URL

The universal link that you specify when you enable app-to-app account linking in the developer console. The Alexa app and LWA redirect the user back to this URL after they acknowledge the account linking request.

Scope

Your app must set this to alexa::skills:account_linking to have permission to enable the skill.

Skill ID

The unique identifier of your skill. You can find this in the developer console.

Stage

The skill stage, which depends on whether your skill is published. Until your skill is published, set stage to development. When your skill is published, use live.

response type

The response type must be code, because app-to-app account linking currently supports authorization code grants only.

state

An opaque value that your app uses to maintain state between the current request and the response. For the Alexa app URL, the state value is required. Alexa includes this state as-is in the response when it redirects the user back to your app using your redirect URLs. You must validate the incoming requests using state to prevent cross-site request forgery.

Make sure that the state that you generate doesn't contain &, =, , /, \, <, >, , #, or |. You can use a base64 URI as a safe way to do this. For an example implementation, see the state helper code example in Step 4: Get the user's Amazon authorization code.

You can generate the state using secure random number generator, and save it to your user session for validation. Alternatively, you can generate the state from your backend server and using a key to encrypt and decrypt it.

Key steps

This section describes key steps, and provides code examples for an iOS app (10.0 or higher) 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  6  7  8

Step 1: Display an account linking option in your app

Your app needs to have a screen from which a user can initiate skill enablement and account linking. This page should show what the user can do by linking their account with Alexa, such as ordering a car by voice.

Step 2: Enable universal links for your app

To allow the Alexa app to redirect the user to your app, you must enable universal links for your app.

Step 3: Configure the skill to use app-to-app 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 things like your app's redirect URLs, access token URL, and so on.

Step 4: Get the user's Amazon authorization code

Your app needs to get the user's Amazon authorization code so that it can later exchange it for an Amazon access token. The Amazon access token will enable the app to enable the skill and complete account linking. The Amazon authorization code is valid for 5 minutes.

Step 5: Exchange the Amazon authorization code for an Amazon access token

After your app receives the user's Amazon authorization code, you need to use it to get the Amazon access token. You need the access token to call the Alexa service to enable the skill and complete account linking.

Step 6: Enable the skill and complete account linking

Now that your app has the user's Amazon access token, your backend server can call the Alexa Skill Activation API to enable the skill and complete account linking.

Step 7: Display the account linking status in your app

Let the user know the account linking status by displaying it in your app, such as in the screenshots in User experience and Errors.

Step 8: 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.

Errors

This section describes possible errors that can occur when account linking or skill enablement fails. When an error occurs, your app should show the appropriate error message to the user. The following image shows one example; this section lists others as well.

Alexa app-to-app account linking error

Error descriptions

This section describes error scenarios that can occur when a user tries to initiate app-to-app account linking. Your app must inform the user that account linking failed, and provide the appropriate error message to the user. This section provides error messages and gives possible causes of the errors. For the best user experience, we encourage you to use the error messages we provide here.

There are three points in the app-to-app account linking flow where your app might receive an error from Alexa:

Errors when obtaining the Amazon authorization code

If an error occurs when your app tries to get the Amazon authorization code, the redirect_uri that the Alexa app uses to redirect the user back to your app will include an error query parameter, as described by the OAuth 2.0 specification. The Alexa app and the LWA fallback both follow the OAuth 2.0 specification, so they both return the same error codes to your app. For more information about why the request to get the Amazon authorization code failed, you can check the error_description query parameter and the OAuth 2.0 specification description for that error code.

Error code Message to show to user Possible causes

invalid_request

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

Request is missing state, scope, and/or response_type

unauthorized_client

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

The provided client_id doesn't have access to request consent to link the user's account

access_denied

None. (The user shouldn't see an error message because they were the one who denied the access.)

The user rejected the request to link their account

unsupported_response_type

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

Parameter response_type isn't equal to code

invalid_scope

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

Invalid scope parameter

server_error

Sorry, Alexa encountered an unexpected error while trying to link your account. Please try again.

Unexpected server error

temporarily_unavailable

Sorry, Alexa encountered a momentary error while trying to link your account. Please try again later.

Temporary server error

Errors when exchanging the Amazon authorization code for an Amazon access token

If an error occurs exchanging the Amazon authorization code for the Amazon access token, the Amazon token server will respond with a 400 Bad Request status code and the body's JSON response will include an error parameter, as described by the OAuth 2.0 specification. For more information about why the request to obtain the Amazon access token failed, you can check the error_description parameter of the JSON response and the OAuth 2.0 specification description for that error code.

Error code Message to show to user Possible causes

invalid_request

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

Missing client_id, client_secret, grant_type, and/or code

invalid_client

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

Invalid client_id and/or client_secret

invalid_grant

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

The request's code (Amazon authorization code) is invalid

unauthorized_client

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

The provided client_id doesn't have permission to request consent to link the user's account

unsupported_grant_type

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

The request's grant_type isn't authorization_code

Errors when calling the Alexa Skill Activation API

If an error occurs when your app calls the Alexa Skill Activation API to enable and link the user's account, the API will respond with a status code that says why the request failed. Otherwise, the API will respond with a 200 OK. For more information about why the skill activation request failed, you can check the message parameter of the JSON response.

HTTPS status code Message to show to user Possible causes

400 Bad Request

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

  • Missing skill_id, stage, accountLinkingRequest.authCode, accountLinkingRequest.redirectUri, and/or accountLinkingRequest.Type
  • Error requesting your app's access/refresh token pair from your app's token server

403 Forbidden

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

  • The Amazon access token is invalid
  • The Amazon access token doesn't have the user's consent to enable the skill
  • The Amazon access token doesn't belong to the skill_id provided in the request
  • The user is not entitled to enable the skill with the specified skill_id provided in the request

404 Not Found

We are experiencing a problem connecting with Alexa to link your account. Please try again later.

  • Invalid skill_id and/or stage

500 Server Error

Sorry, Alexa encountered an unexpected error while trying to link your account. Please try again.

  • Unexpected server error
  • Problem linking accounts with your app's OAuth 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.
  • Prior to account linking – Before redirecting the user to the Alexa app or LWA, ask the user for any other information you require for account linking (additional details, consent, a PIN, and so on).
  • 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.
  • URL generation – In your code to Get the user's Amazon authorization code, we highly recommend that you assemble the Alexa app URL and LWA fallback URL in your backend server, and then pass the assembled URLs to your app. This enables you to quickly change parameters (such as the stage) without rebuilding your app.

Testing guidelines

In addition to making sure that your skill meets the certification requirements that apply to all skills, we recommend that you test the following aspects:

  • When the Alexa app is installed, you are able to complete account linking when it is initiated from your app using the Alexa app flow.
  • When the Alexa app is not installed, you are able to complete account linking when it is initiated from your app or website using the LWA flow. If your implementation does not support the LWA flow, your app or website provides a graceful error message to the user.
  • When account linking fails, your app or website provides a graceful error message to the user.

Also be sure to beta test your skill. When you enable beta testing, do not forget to add beta testers.

Note that, until your skill is published, you must set the stage value to development when you use the Alexa app URL and the Alexa Skill Activation API. When your skill is published, use live.

Frequently asked questions

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

How do I know if the Alexa app is not installed on the user's mobile device?

For an example of how to determine this in iOS, go to Example: Open the URLs in Step 4: Get the user's Amazon authorization code.

To protect user trust, app-to-app account linking requires user consent for a specific skill. If you want to link a user's account for more than one Alexa skill, you must take the user through the linking flow more than once.

How do I check if the skill is already enabled and the account is already linked?

You make a GET request to the Alexa Skill Activation API.

What if the skill is already enabled and the account is already linked?

In this case, when you make a POST request to the Alexa Skill Activation API, the user's account will be relinked and you will receive a successful response.

How can I get notified when account linking is complete?

You can subscribe to the Account Linked event.

If a user wants to link Alexa with a different account, they should first log in to your app with the other account and then initiate account linking from within your app. Your app can choose to provide an option to switch accounts within the account-linking flow.

What if a user is not an existing Alexa user and they don't have the Alexa app installed?

If a user has an Amazon account but is not an Alexa user, they can simply sign in to the LWA page with their Amazon credentials and then acknowledge the linking request. If a user does not have an Amazon account, they can create a new Amazon account on the LWA screen and complete account linking for the skill. The user, however, will need an Alexa-enabled device or Alexa app in order to use Alexa features.

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. You can disable the skill and unlink the account for the user by making a DELETE request to the Alexa Skill Activation API.

What happens when a user disables my skill? Am I notified?

To get notified when a user disables your skill, you can subscribe to skill disabled events. When the skill is disabled, you should revoke your access token and delete the Amazon access token for the user. Alexa also deletes the access token that your service provided, and revokes the Amazon access token.

What if my smart home skill needs permissions? Can I get these during app-to-app account linking?

Permissions (such as device address and user profile information) are currently not part of the app-to-app account linking flow. When the user invokes the skill with an intent that needs permissions, you will need to prompt users, through a permissions card, for the respective permissions. Users can grant permissions through their Alexa app during skill runtime.