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 system 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:

• App-to-app starting from your app – Users link their account by starting from your app or website instead of the Alexa app. For details, see App-to-App Account Linking (Starting From Your App).
• Alexa app only (browser flow) – Users accomplish account linking entirely within the Alexa app. This flow is the most common. For details, see Choosing an account linking flow.

If you have an app or website and can obtain an authorization grant for your user without requiring them to log in again, Amazon encourages 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.

For troubleshooting information, see Troubleshooting app-to-app account linking (starting from the Alexa app).

• Terminology
• User experience
• Which flow to implement
• How it works
• Parameters for the authorization request to your app
• Key steps
• Best practices
• Testing guidelines
• Frequently asked questions
• Related topics

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 for iOS) If the user doesn't have your app installed on their iOS device, the flow is the same as the Alexa-app only account linking flow. That is, the user's browser opens your authorization page specified by Your Web Authorization URI in the skill settings in the developer console, asking the user to acknowledge the account linking request. After the user acknowledges the request, the authorization website returns the user to the Alexa app.
• (Browser flow for Android) If the user doesn't have your app installed on their Android device, the user's browser opens to the page specified by Your Android App Authorization URI, 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. For all options, 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.

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).

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 and other workflows like device discovery start on the Alexa app.

Parameters for the authorization request to your app

The authorization request that the Alexa service makes to your app by using the Universal Link (iOS) or App Link (Android) that you provide includes the following parameters.

Key steps

Review the key steps and code examples for an iOS app (10.0 or higher) and an Android app. The examples use the following libraries and languages:

• iOS app – Swift 4
• Android app – Kotlin

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

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).

How to do it

Example: Enable Universal Links (iOS)

Example: Enable 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.

How to do it

Example: Configure the skill with the developer console

Example: Configure the skill with the CLI

Example: Configure the skill with REST API

{
  "accountLinkingRequest": {
     "accessTokenScheme": "HTTP_BASIC",
     "accessTokenUrl": "https://api.amazon.com/auth/o2/token/",
     "authorizationUrl": "https://www.amazon.com/ap/oa/",
     "clientId": "yourSMAPIClientId",
     "clientSecret": "yourSMAPIClientSecret",
     "domains": [],
     "authorizationUrlsByPlatform": [
      {
        "platformType": "iOS",
        "platformAuthorizationUrl": "https://youriOSURL"
      },
      {
        "platformType": "Android",
        "platformAuthorizationUrl": "https://yourAndroidURL"
      }
     ],
     "scopes": ["profile"],
     "skipOnEnablement": true,
     "type": "AUTH_CODE"
  }
}

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.

How to do it

https://yourAppAuthUrl?
response_type={Response Type}&
client_id={Client ID}&
scope={Scope}&
state={State}&
redirect_uri={Redirect URI}

Example: Handle the authorization request (iOS)

// Handler for Universal Links in AppDelegate
// Add this method to handle incoming Universal Links
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let incomingURL = userActivity.webpageURL else {
            return false
    }

    guard let components = NSURLComponents(url: incomingURL, resolvingAgainstBaseURL: true),
        let queryParameters = components.queryItems else {
            return false
    }
    
    let AUTH_REQUEST_PARAMETERS: Set = ["redirect_uri", "state", "scope", "client_id", "response_type"]
    var validatedParameters : [String: String] = [:]
    for queryParameter in queryParameters {
        if AUTH_RESPONSE_PARAMETERS.contains(queryParameter.name) {
            validatedParameters[queryParameter.name] = queryParameter.value
        }
    }

    let initialViewController = UIStoryboard(name: "Main", bundle: nil).instantiateViewController(withIdentifier: "appToAppConsentScreen") as! AppToAppScreenViewController
            initialViewController.authorizationRequest = validatedParameters
            self.window?.rootViewController = initialViewController
            self.window?.makeKeyAndVisible()
            return true

}

// Create this controller for the consent screen
class AppToAppScreenViewController: UIViewController {
    
    var authorizationRequest : [String: String]?
    
    override func viewDidLoad() {
        super.viewDidLoad()
    }
    
    
    @IBAction func acceptButtonClicked(_ sender: UIButton) {
        guard let responseUri = 
            callBackendForAuthorization(authorizationRequest: authorizationRequest, "ACCEPT") else {
                return
        }
        
        // implementation of this method shown in the following step
        openUrl(alexaUrl: responseUri)
    }
    
    @IBAction func denyButtonClicked(_ sender: UIButton) {
        
        guard let responseUri = 
            callBackendForAuthorization(authorizationRequest: authorizationRequest, "DENY") else {
                return
        }
        
        // implementation of this method shown in the following step
        openUrl(alexaUrl: responseUri)
    }
}

Example: Handle the authorization request (Android)

class AppToAppConsent : AppCompatActivity() {
 
     // Constants
     private val QUERY_PARAMETER_KEY_CLIENT_ID = "client_id"
     private val QUERY_PARAMETER_KEY_RESPONSE_TYPE = "response_type"
     private val QUERY_PARAMETER_KEY_STATE = "state"
     private val QUERY_PARAMETER_KEY_SCOPE = "scope"
     private val QUERY_PARAMETER_KEY_REDIRECT_URI = "redirect_uri"

     private val USER_ACCEPT = "ACCEPT";
     private val USER_DENY = "DENY";

     // Incoming Query Parameters
     private var clientId: String? = null
     private var responseType: String? = null
     private var state: String? = null
     private var scope: String? = null
     private var redirectUri: String? = null
     private var url: String? = null
 
     private lateinit var acceptButton: Button
     private lateinit var denyButton: Button
 
 
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         val appLinkData = intent.data
 
         // Get values from App Link
         clientId = appLinkData.getQueryParameter(QUERY_PARAMETER_KEY_CLIENT_ID)
         responseType = appLinkData.getQueryParameter(QUERY_PARAMETER_KEY_RESPONSE_TYPE)
         state = appLinkData.getQueryParameter(QUERY_PARAMETER_KEY_STATE)
         scope = appLinkData.getQueryParameter(QUERY_PARAMETER_KEY_SCOPE)
         redirectUri = appLinkData.getQueryParameter(QUERY_PARAMETER_KEY_REDIRECT_URI)
 
         setContentView(R.layout.activity_consent_screen)
         initializeComponents()
     }
 
     private fun initializeComponents() {
  
         acceptButton = findViewById(R.id.btn_accept_linking)
         acceptButton.setOnClickListener {
             val responseUri = callBackendForAuthorization(clientId, responseType, state, scope, redirectUri, USER_ACCEPT)

             // implementation of this method shown in the following step
             openUrl(responseUri)
         }
 
         denyButton = findViewById(R.id.btn_decline_linking)
         denyButton.setOnClickListener {
             val responseUri = callBackendForAuthorization(clientId, responseType, state, scope, redirectUri, USER_DENY)

             // implementation of this method shown in the following step
             openUrl(responseUri)   
         }
     }
}

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.

How to do it

https://alexaAppRedirectUri?
code=yourServiceCode&
state=authorizationRequestState&
source=app

https://alexaAppRedirectUri#
token=yourServiceToken&
token_type=Bearer&
expiration_time=3600&
state=authorizationRequestState&
source=app

https://alexaAppRedirectUri?
error=access_denied&
state=authorizationRequestState&
error_description=The%20user%20denied%20the%20request.%20

https://alexaAppRedirectUri#
error=access_denied&
state=authorizationRequestState&
error_description=The%20user%20denied%20the%20request.%20

Example: Redirect the user to the Alexa app (iOS)

private func openUrl(alexaAppUrl: URL) {
    UIApplication.shared.open(alexaAppUrl)
}

Example: Redirect the user to the Alexa app (Android)

private fun openUrl(alexaAppUrl: String) {
    startActivity(Intent.ACTION_VIEW, Uri.parse(alexaAppUrl))
}

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.

How to do it

Best practices

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

• Platform specific fallback mechanism – In Android, Alexa uses the value of the Your Android App Authorization URI field as the fallback authorization URI when the user doesn't have your app installed. In iOS, Alexa uses the value of the Your Web Authorization URI field as the fallback authorization URI when the user doesn't have your app installed.
• User interface – When designing your app's user interface, follow the Alexa Brand Guidelines for Amazon Developers.
• 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 you publish 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 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 Request Access to the Alexa Event Gateway.

Related topics

• App-to-App Account Linking (Starting From Your App)
• Add Account Linking to Your Alexa Skill

Last updated: Sep 10, 2024