Alexa-Initiated App-to-App Account Linking

App-to-app account linking enables users to link their Alexa identity with your service by starting from the Alexa app. When users sign in to both apps on their mobile device, they can link their accounts without re-entering credentials. This flow supports iOS and Android.

Alexa supports the following other app-to-app implementation options:

  • App-to-app starting from your app – Users start the linking process from your app or website instead of the Alexa app. This flow supports the authorization code grant type only. For details, see App-Initiated App-to-App Account Linking.
  • Alexa app browser flow – Users complete account linking entirely within the Alexa app. This flow is the most common and supports both authorization code and implicit grant types. For details, see Standard Account Linking.

If you have an app or website and can obtain an authorization grant without requiring users to log in again, Amazon recommends that you implement the app-to-app account linking flows in addition to the standard account linking 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.

Before you begin

Make sure you complete the following items:

How it works

App-to-app account linking works by using OAuth 2.0. The following steps describe the flow when your app is installed on the user's device:

  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: The Alexa app falls back to the standard account linking experience described in Account linking methods.
  4. The Alexa app sends the authorization response from step 3 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 provided.
    • Authorization code grant: The Alexa service calls your token server to exchange the authorization code for an access and refresh token pair, and then stores the access and refresh token pair. If your token server supports PKCE and you enabled PKCE in the developer console or CLI, Alexa includes the code_verifier.
  5. The account linking process is complete and other workflows, such as device discovery, start on the Alexa app.

URIs and endpoints

In the standard account linking flow, the Alexa app opens a web-based authorization URI in the user's browser. In the app-to-app flow, the Alexa app instead opens a deep-link-enabled URI that launches your mobile app directly.

In the app-to-app account linking flow, starting from the Alexa app, you specify the following URIs. Only provide a URI for the platforms your app supports. The app authorization URIs serve a different purpose than the web authorization URI and they typically point to different endpoints. The URIs must comply with the URI syntax.

Developer console field CLI and REST field Description

Your Web Authorization URI

authorizationUrl

Your web-based authorization page. Used as the iOS fallback when your app isn't installed.

Your iOS App Authorization URI

authorizationUrlsByPlatform

A Universal Link that opens your iOS app to handle the authorization request.

Your Android App Authorization URI

authorizationUrlsByPlatform

An App Link that opens your Android app. Also used as the Android fallback when your app isn't installed.

Query parameters

The Alexa service appends the following query parameters to the appropriate configured URI in the authorization request to your app.

Field Description

client_id

An identifier for your skill. Use the client_id 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.

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 standard account linking flow uses. You must register these URIs with your authorization server. These URIs are Universal Link and App Link-enabled. The redirect URI depends on the grant type you configured for your skill.

For the authorization code grant type, use 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}` <br><br>    
For the implicit grant type, use 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 more details, see [Alexa Redirect URLs](../account-linking/configure-authorization-code-grant.html#redirect-url-values).

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 as follows:

  • Your service defines the scope.
  • 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're 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.

code_challenge

The hashed value of the PKCE code_verifier. Included if you enabled PKCE for your skill. For details about how to enable PKCE, see Step 2: Configure the skill for account linking.

code_challenge_method

The method to use to transform the code_verifier. Included if you enabled PKCE for your skill. For details about how to enable PKCE, see Step 2: Configure the skill for account linking.

Steps to implement app-to-app account linking in your app

To implement app-to-app account linking in your iOS app (iOS 10.0 or higher) or Android app (Android 12 or higher), complete the following steps. Each step includes platform-specific code examples in Swift 4 (iOS) and Kotlin (Android).

Step 1:
Enable Deep Linking
→
Step 2:
Configure Authorization URLs
→
Step 3:
Handle the Authorization Request
→
Step 4:
Redirect to the Alexa app

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 you start, make sure that you complete the following items:

  • Install both your app and the Alexa app on the mobile devices.
  • Sign in to both apps.
  • Enable the skill through the Alexa app.

Verify the following account-linking features:

  • After you enable your skill or open the skill card to link accounts in the Alexa app, verify that your app opens a landing page that provides a confirmation for users to proceed with account linking.
  • After accepting or denying account linking in your app, confirm that the Alexa app opens and displays the linking complete message.
  • Interact with the skill to make sure 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.

For troubleshooting information, see Troubleshooting Alexa-initiated app-to-app account linking.

Next steps

After you implement the authorization flow, see Use Access Tokens in Your Skill Code to handle the access token in your skill's request handler.

For smart home and video skills, see Send Events to the Alexa Event Gateway to understand how your skill sends asynchronous events after account linking.

Was this page helpful?

Last updated: Jul 14, 2026