Best Practices for Account Linking

Account linking adds an extra step to skill enablement, making a smooth experience essential. Follow these best practices to prevent negative skill reviews related to account linking.

Users are redirected to your login page in the standard account linking flow and in the fallback browser flow in app-to-app account linking. You specify the login page authorization URI when you configure account linking.

Provide clear instructions

Make it clear that users must log in with credentials for your service, not their Amazon account. Users may be confused about which account they need to use.

Clearly brand your log-in page

Display your brand with clear, unambiguous messaging. If your company has acquired other companies, make sure all relevant brands are represented so existing and new users can recognize the service they are linking.

Provide the log-in page in the user's language

For a consistent user experience, your log-in page should use the same language as the Alexa app. To get the language, check the Accept-Language HTTP request header for the user’s preferred language. If the Accept-Language header is not available, check the browser language configuration navigator.language or navigator.browserLanguage property.

Support the same authentication providers in the skill log-in page as you do on your website or app. For example, if your website supports sign-in with Facebook, Twitter, Google, or Login with Amazon, your skill log-in page should support those providers too.

Include validation

Include form-field validation on your log-in page before you attempt authentication. When validating the user input, keep the following items in mind:

Strip leading and trailing whitespace from user-entered values, or warn the user about unintended leading or trailing spaces.
Don't set default input to capital letters on case-sensitive fields, especially on mobile devices with soft keyboards.
Apply region-specific validation rules for fields, such as phone numbers and postal codes. Clearly communicate validation errors to the user.
Turn off auto-correct and auto-capitalize on username and email input fields.

Provide clear error descriptions

When a user encounters an error, such as log-in failure, communicate the problem clearly and concisely, and tell the user how to correct it. Avoid vague messages such as, “An error occurred”.

Limit the links

Only include links on your log-in page that are directly relevant to account linking. Extraneous links, such as navigation menus, promotional content, increase the chance that users abandon the log-in flow.

Support account recovery

Users often forget their username or password for a service. Include account recovery options on the log-in page so that users who have forgotten their credentials can recover without abandoning the flow.

Help your users get help

Provide clear guidance on how users can contact your support team if they encounter problems that they cannot resolve through the log-in page.

Design for mobile devices

Since most users complete account linking on mobile devices, add a reminder to design and test the log-in page for mobile screen sizes and touch interactions first.

Specify your authorization URI

Unless you implement app-to-app account linking starting from the Alexa app, don't use the same authorization URI for both of the following:

The Your Web Authorization URI entry on the account linking page of the Alexa developer console
The authorization URI in your app configured as App Links or Universal Links. If you use the same URI for both cases, the authorization URI opens in your app, which leads to account linking failures.

Design for app-to-app account linking

The following best practices apply to the app-to-app account linking flows.

Follow Alexa brand guidelines

Follow the Alexa Brand Guidelines for Amazon Developers when designing your app’s UI. Use approved Alexa logos, colors, and button styles.

Get all required information before redirecting

Collect any additional information, consent, PINs, or security question answers you need before you send or redirect the user to the Alexa app or Login with Amazon. If the request includes a financial transaction or involves personal information, ask the user to answer a security question before fulfilling their request. Redirecting users back to your app mid-flow to collect missing information creates confusion and increases abandonment.

Assemble URLs in the backend

Amazon recommends that you generate the response URIs server-side rather than in your mobile app. This approach lets you change parameters, endpoints, or validation logic without rebuilding your app.

Verify App Links and Universal Links

Before publishing, confirm that your app correctly handles Android App Links and iOS Universal Links. Test that the links open your app directly and that the fallback to a browser works when your app isn't installed on the user's device.

Test on both platforms separately

If you support both iOS and Android, test the full account linking experience on each platform independently before you publish your skill. Behavior differences between platforms are common.

App-to-app starting from your app

For the app-to-app account linking flow where the user starts from your app or website, you can offer account linking in multiple places. For example, you can give users the option to enable account linking after they register your app or provide them with a button on your settings page.

Follow these additional best practices for the app-to-app account linking flow where the user starts from your app or website.

Use the least number of clicks

Minimize the steps required to start account linking. Aim for no more than three clicks from your app’s home screen to the account linking flow. The fewer steps, the higher the linking completion rate. Example flow A (2 clicks):

Click 1: Home screen → Alexa linking settings page
Click 2: Alexa linking settings page → Link your account button

Example flow B (3 clicks):

Click 1: Burger menu → Settings page
Click 2: Settings page → Voice assistant section
Click 3: Voice assistant section → Link your account button

Surface the Alexa integration

Make the user aware of the Alexa integration the first time they use your app. Prompt users to link their accounts as part of onboarding. Always provide an option to skip the linking process, along with information about where users can find the feature later.

Review your voice assistant settings

If your app has settings related to voice assistants, make account-linking accessible from the voice assistant settings. Users looking for Alexa integration will often check settings menus and voice assistant sections first.

Promote account linking to unlinked users

Inform unlinked users about your account linking feature. Drive targeted communications to users who are not yet linked. Use push notifications, in-app prompts, what’s new screens, release notes, blog posts, and emails. Don't target users who are already linked.

Display the correct account linking status

Use the Get account linking and skill status request to the Alexa Skill Enablement REST API to check whether a user’s account is currently linked or unlinked, and display the appropriate Link or Unlink button accordingly. Subscribe to the Skill Disabled Event to receive a notification when a user disables and unlinks your skill, so your app can update its displayed status promptly. Don't rely solely on the presence of the Amazon access and refresh token pair to determine link status.

Provide clear messaging

Handle all account linking user flow states with context-specific messages. Follow these guidelines:

Show a success message after linking completes; include example voice commands the user can try immediately.
Show progress indicators when there is a delay during the linking process.
Implement automated retry logic for timeout errors to reduce user frustration.
Don't show generic “Oops” messages when a user intentionally cancels account linking.
Don't show an “already linked” message immediately after a user successfully completes linking.
Avoid generic error screens. Show the right message at the right time.

Implement unlinking within your app

Persist the Amazon access and refresh token pair that you receive after account linking completes. You need this token pair to make the Disable skill and unlink account request to the Alexa Skill Enablement REST API when the user chooses to unlink from within your app.

Handle users who didn't use app-to-app linking

Some users link their accounts through the Alexa app directly rather than through your app’s app-to-app flow. For these users:

Deep-link to the skill page in the Alexa app so they can unlink from there.
The link on your skill page looks similar to the following examples:
- Android: https://alexa.amazon.com/spa/index.html#skills/dp/{skillAsin}
- iOS: https://alexa.amazon.com/spa/index.html#skills/dp/{skillAsin}
Provide a fallback URL that opens the skill page in a browser if the Alexa app is not installed.
Redirect your users to https://www.amazon.com/dp/{skillAsin}

Note: To find the Amazon Standard Identification Number (ASIN) for your skill, browse to your skill in the Alexa Skills Store. The ASIN is the 10-digit alphanumeric ID in the URL. For example, in the URL www.amazon.com/gp/product/A1A1A1A1A1, the ASIN is A1A1A1A1A1.

Notify unlinked users

When a user unlinks their account, inform them about the account linking feature and invite them to re-link. Use push notifications, in-app pop-ups, release notes, or other appropriate channels.

Verify that your redirect URI works

Make sure that the redirect URI you register in the Alexa developer console can complete account linking even when opened inside a web view. Some versions of LWA don't trigger Universal Links or App Links when returning from the authorization page, so the redirect URI must handle the web view case as a fallback.

App-to-app starting from the Alexa app

The following best practices apply to the app-to-app account linking flow where the user starts from the Alexa app.

Configure platform-specific fallback mechanisms

Configure web authorization URIs to handle the case where the user doesn't have your app installed on their device. For Android, Alexa uses the Your Android App Authorization URI field as the fallback when the user doesn’t have your app installed. For iOS, Alexa uses the Your Web Authorization URI field. For details about configuring these URIs, see Configure Account Linking in the Alexa Developer Console.

Platform	Your app is installed	Fallback URI
Android	Alexa opens your app using your Android App Authorization URI	Alexa opens your web view using your Android App Authorization URI
iOS	Alexa opens your app using your iOS Universal Link	Alexa opens your web view using your Web Authorization URI

Token management

Proper token management reduces the number of customers forced to relink their accounts due to expired tokens. Follow Amazon requirements for access and refresh token management.

Testing account linking

Review the following guidelines for best practices for testing the account-linking flow of your skill.

Test from a variety of devices and browsers

Most users use their mobile devices to enable skills and complete account linking. Your log-in page could display on various operating systems and operating system versions, as well as on different screen sizes. Make sure the following items work correctly:

Test on popular desktop operating systems like Windows and macOS. Make sure to test on the newest version as well as other supported versions.
Test the most popular browsers, like Firefox, Chrome, Internet Explorer, and Safari.
Test against the most recent versions of iOS and Android.
Test on different form factors, such as phones and tablets.
Test with different screen sizes and orientations.

Users might navigate away from the log-in page. Make sure the following items work correctly:

All links on your log-in and account linking pages work correctly.
Forward and backward browser navigation doesn't break the linking flow.
Complete the full account linking flow after navigating away from and returning to the log-in page.

Test the flow for new user accounts

Remember that an Alexa skill can help gather new users to your service. Support and test the new-account creation path through skill enablement and account linking, including any validation steps for new accounts.

Test account recovery

Users often forget their account credentials. Verify the following scenarios:

Simulate failed log-in attempts and verify that CAPTCHA and lockout mechanisms work correctly.
Test edge cases that might interfere with the log-in process: unverified accounts, expired subscriptions, suspended accounts, and blocked accounts.

Test multi-factor authentication

Test the complete account linking flow with multi-factor authentication enabled. Make sure that multi-factor authentication prompts don't break the linking flow.

Miscellaneous

Review the following guidelines for other best practices.

Make sure that you need account linking

Account linking adds friction to skill enablement. If your skill type doesn't require account linking, consider whether one of the following alternatives meets your needs:

User ID attribute – Persist user-specific data between sessions without account linking. For details about session.user.userId, see Request and Response JSON Reference.
Permissions feature – Request user information such as address, email address, or location without account linking. For more details, see Configure Permissions for Customer Information in Your Skill.

Make sure that users can switch accounts

If a user disables your skill and then re-enables it, require the user to log in again. Do not reuse the previous session or tokens automatically so that users who share a device can link different accounts.

Watch your response header size

Keep response headers under 2,000 characters to avoid page-loading issues during account linking. If your headers are close to or exceed this limit, consider eliminating cookie values that are unrelated to OAuth.

Redirect the user after log-in

For standard account linking and app-to-app account linking starting from Alexa, redirect the user back to the Alexa app after they complete the log-in step on your app or web page. Register the Alexa redirect URLs with your authentication provider to ensure that the redirect is permitted. You can find the redirect URLs in the redirect_uri parameter of the authorization request URL and on the account linking page of the Alexa developer console.

Was this page helpful?

Provide feedback

Last updated: Jul 14, 2026