App-Initiated App-to-App Account Linking

The app-to-app account linking flow, starting from your app, enables users to link their Alexa user identity with their identity in another service by starting from your app or website. When you support the account linking flow from your app, your users can:

Discover your Alexa skill through your app.
Start 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're logged in to both of the apps on their mobile device.
Link their account from your app using the Login with Amazon (LWA) authorization server, when the Alexa app isn't installed on their mobile device.

Feature support for this account linking flow includes the following:

Launching the Alexa app from your app – iOS and Android
Login with Amazon – Web and as a fallback for iOS and Android
OAuth 2.0 authorization code grant with PKCE – LWA supports Proof Key for Code Exchange (PKCE) security measures in the authorization code grant account linking flow. This process verifies that the token request comes from the same client that initiated the authorization request, preventing authorization code interception attacks.

Account linking supports the following other implementation options:

App-to-app starting from the Alexa app – Users link their account by starting from the Alexa app instead of your app. For details, see App-to-App Account Linking (Starting From the Alexa App). This flow supports both authorization code and implicit grant types.
Alexa app only (browser flow) – Users accomplish account linking entirely within the Alexa app. This is the most common flow. For details, see Choosing an account linking flow. This flow supports both authorization code and implicit grant types.

If you have an app or website, implement one of the app-to-app account linking flows in addition to the Alexa app-only flow.

Tip: To receive Works with Alexa (WWA) certification, if your device has a mobile app, you must implement both versions of app-to-app account linking, starting from your app and starting from the Alexa app.

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

Before you begin

Make sure you complete the following items:

Verify that your authorization server meets the requirements defined in Requirements for Account Linking. LWA supports Proof Key for Code Exchange (PKCE) security measures in the authorization code grant account linking flow. This process verifies that the token request comes from the same client that initiated the authorization request, preventing authorization code interception attacks.
Configure account linking for your skill using the authorization code grant type.
Verify that you have an iOS app (iOS 10.0 or higher) or Android app (Android 12 or higher) where you want to implement the account linking flow.
Review Best Practices for Account Linking.

How it works

App-to-app account linking works by using OAuth 2.0. The following steps describe the authorization code grant flow to link the user accounts. The flow assumes the user installed and signed in to your app on their mobile device. For details about the URLs mentioned, see URLs and endpoints.

The following diagram shows the account linking flow when the user starts account linking from your app on their mobile device. Here, your app obtains the access token from LWA as described in steps 1–9. (Click image to enlarge.)

App-to-app account linking authorization code grant flow

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

After the user acknowledges the linking request, your app backend starts the account linking flow. If your backend supports PKCE, it generates the code_verifier and derives the code_challenge using SHA-256, as defined in RFC 7636. Then, the backend returns the Alexa app and LWA website URLs to your app.
What happens next depends on whether the user installed the Alexa app on their mobile device.
- If the Alexa app is installed:
  1. Your app launches the Alexa app by using the Alexa app URL with the authorization request parameters. For details, see Alexa app and LWA fallback URL query parameters.
  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.
- If the Alexa app isn't installed:
  1. Your app launches the LWA website at the LWA fallback URL in an in-app browser tab (not a native browser app) with the authorization request parameters, and Alexa app and LWA fallback URL query parameters.
  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.
In both cases, if you include PKCE parameters in the authorization request, LWA temporarily stores the code_challenge and code_challenge_method along with the authorization code.
If the user agrees to link the accounts and logs in successfully, the Alexa app or LWA sends the user back to your app using your redirect URLs, and, on success, includes the user's Amazon authorization code and state as a part of that redirect.
Your app forwards the authorization code to your app backend.
Your backend sends a token request to the LWA token URL and exchanges the Amazon authorization code for an Amazon access token.

LWA verifies the authorization code. If the request includes the PKCE parameter, LWA uses the code_verifier to verify the token endpoint, based on the stored PKCE parameters, as defined in RFC 7636.
If these values match, LWA issues access and refresh tokens and the user's Amazon account is now linked to their account in your service. If they don't match, LWA returns an error.
Your backend app calls your authorization server to get the user's authorization code for their account in your service.
Your backend app calls the Alexa Skill Enablement API with the user's Amazon access token and the user's authorization code for your service, to enable the skill and link the accounts.

The Alexa service sends a token request 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.
The user's account in your service is now linked to their Alexa account, and the skill is ready for use.

URLs and endpoints

Your app needs the following URLs and endpoints for app-to-app account linking.

Name	Where it's used	Details
Alexa app URL	Your app uses this Universal Link (iOS) or App Link (Android) to send the user to the Alexa app to acknowledge the linking request. For parameter descriptions, see Alexa app and LWA fallback URL query parameters. For general information about Universal Linking, see Allowing Apps and Websites to Link to Your Content in the Apple 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}&code_challenge={hashed value}&code_challenge_method=S256` For example: `https://alexa.amazon.com/spa/skill-account-linking-consent?fragment=skill-account-linking-consent&client_id=amzn1.application-oa-client-1&scope=alexa::skills:account_linking&skill_stage=development&response_type=code&redirect_uri=https://yourAppRedirectUri&state=aGVsbG8&code_challenge=AB12CCEXAMPLE &code_challenge_method=S256`
LWA fallback URL	A link that sends the user to LWA to enter their Amazon credentials. The URL works for iOS, Android, and websites. Your app uses this link when 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}&code_challenge={hashed value}&code_challenge_method=S256` For example: `https://www.amazon.com/ap/oa?client_id=amzn1.application-oa-client-1&scope=alexa::skills:account_linking&response_type=code&redirect_uri=https://yourAppRedirectUri&state=aGVsbG8&code_challenge=AB12CCEXAMPLE&code_challenge_method=S256`
Your app's redirect URLs	The Alexa app (or LWA, if the Alexa app isn't installed) uses this Universal Link or App 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 URLs by using the Alexa developer console, ASK CLI, or Account Linking REST API. For the required syntax, see 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 by using the developer console, the ASK CLI, or Account Linking REST API.
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 the access token URL by using the developer console, the ASK CLI, or Account Linking REST API.
LWA authorization service	Your backend server uses a `POST` request to exchange the user's Amazon authorization code for an Amazon access token. This flow 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 Enablement API endpoint	Your backend server calls this endpoint to enable the skill for the user. For details, see Alexa Skill Enablement API.	Format: `https://api.amazonalexa.com/v1/users/~current/skills/{yourSkillId}/enablement` Depending on the user's location, the base URL could be `https://api.amazonalexa.com`, `https://api.eu.amazonalexa.com`, or `https://api.fe.amazonalexa.com`.

Alexa app and LWA fallback URL query parameters

Alexa supports the following parameters in the query string in the Alexa app and the LWA fallback URLs.

Parameter	Description
`client_id`	The Alexa client ID that the Alexa developer console provides when you enable app-to-app account linking in the developer console.
`client_secret`	The Alexa client secret that the developer console provides when you enable app-to-app account linking in the developer console.
`redirect_uri`	The Universal Link or App 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 completing the account linking request.
`scope`	Your app must include the `alexa::skills:account_linking` scope to obtain 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. Until you publish your skill, set `stage` to `development`. After you published your skill, use `live`.
`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. App-to-app account linking supports authorization code grants only.
`state`	An opaque value that your app uses to maintain state between the current account linking 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 at your redirect URLs. You must validate 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 generate the value. 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 a secure random number generator, and save it to your user session for validation. Alternatively, you can generate the state from your backend server and use a key to encrypt and decrypt it.
`code_challenge`	The hashed value of the PKCE `code_verifier`. Include if your app backend supports PKCE using SHA-256. For details, see RFC 7636.
`code_challenge_method`	The method to use to transform the `code_verifier`. Included if your app backend supports PKCE using SHA-256. Account linking supports the SHA-256 code challenge method only.

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.

The examples use the following libraries and programming languages:

iOS app – Swift 4, Alamofire and SwiftyJSON
Android app – Kotlin
Backend server – Node.js v11.12.0, Lodash 4.1.77, and axios 0.18.0

Step 1:
Add Account Linking Options

→

Step 2:
Enable Deep Linking

→

Step 3:
Configure Redirect URLs

→

Step 4:
Make an Authorization Request

→

Step 5:
Make an Access Token Request

→

Step 6:
Enable Your Skill

→

Step 7:
Display Account Linking Status

Errors

When an error occurs during account linking or skill enablement fails, your app should show the appropriate error message to the user. The following image shows one example where the app asks the user to try again later.

Error descriptions

Errors often occur during the following points in the app-to-app account linking flow:

Testing guidelines

In addition to making sure that your skill meets the certification requirements that apply to all skills, test the following account linking flows:

When the Alexa app is installed, you're able to complete account linking when initiated from your app using the Alexa app flow. On Android, if you see a Use a different app selector when opening the Alexa app URL, it means that your version of the Alexa app has invalid App Links. To fix this, delete and re-install the Alexa app.
When the Alexa app isn't installed, you're able to complete account linking when initiated from your app or website using the LWA flow. If your implementation doesn't support the LWA flow, your app or website provides a graceful error message to the user. For details, see How Users Experience Account Linking.
When account linking fails, your app or website provides a graceful error message to the user.
After you complete account linking, you should be able to unlink the account using your app. You should also see the correct button (Link versus Unlink) depending upon the status of your account linking.

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

Also be sure to beta test your skill. When you enable beta testing, don't forget to add beta testers.

For troubleshooting information, see Troubleshooting app-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?

Provide feedback

Last updated: Jul 14, 2026