Account Linking Best Practices for Alexa Skills

Note: Sign in to the developer console to build or publish your skill.

Account linking adds an extra step to the user's skill-enablement process, so it is important that this experience goes smoothly. To help avoid negative skill reviews related to account linking, follow the best practices in this topic.

Some of these best practices refer to parts of the log-in experience that are not applicable to app-to-app account linking, but the overall guidelines still apply.

Designing the log-in page

When a user goes to the Alexa app and enables a skill with account linking, they are immediately redirected to the log-in page that you specify as the authorization URI when you set up the skill for account linking. Review the following guidelines for best practices for the log-in page.

Provide clear instructions

Your log-in page should provide instructions about which user credentials the user must enter. For example, make it clear that the user must log in using credentials for your service, not their Amazon account. Otherwise, they might enter Amazon credentials and become confused when these credentials do not work. If you are using a third-party authentication server, make it clear that the user must log in with credentials for that server.

Clearly brand your log-in page

Make sure that your log-in page displays your brand and includes clear messaging so that users know that this page is associated with your service. If your company has acquired another company, make sure to consider the account-linking experience for both your existing and new users who may now use the same log-in page, which may or may not correspond to the service they signed up for initially.

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

If the user's browser is set to one of the supported languages, the Alexa app attempts to use that language preference to display a localized version of the app. For other languages, the app defaults to en-US.

For a consistent user experience, your log-in page should use the same language as the Alexa app. To get the language, first check the Accept-Language HTTP header. The Alexa app attempts to set this when calling your authorization URI. If the header is not set, you can use the language defined by the user's browser by checking the navigator.language or navigator.browserLanguage property.

Note that the user's browser settings are independent of the language that the user's Alexa-enabled device is configured to use. For example, a user could configure their device to use German, but configure their browser to use UK English. In this case, the Alexa app renders in English and the Accept-Language header is set to English (en-GB).

If your website and/or mobile app supports authentication providers such as Facebook Login, Login on Twitter, Google Sign-In, Login with Amazon, or others, make sure that your skill's log-in page supports these authentication providers also. Otherwise, some users of your service will not be able to link their account with your Alexa skill, or they will be forced to create a new account that is only used with Alexa, which leads to a fragmented or poor user experience.

Include validation

Your log-in page should include form-field validation that verifies that the log-in information is well-formed before authentication is attempted. This prevents error messages that indicate that the user provided incorrect credentials, when the problem is actually an easily caught typo or copy-paste error.

The following are some common validation issues to watch for:

Leading/trailing spaces – Strip out or warn the user about unintended leading or trailing spaces.
Unintentional capitalization – On mobile devices with soft keyboards, be careful not to set the default input to capital letters on case-sensitive fields where the user might not be expecting it.
Region-specific validation – If you are validating fields such as postal codes, addresses, and phone numbers, make sure that the logic you use is correct for every region where your skill is available. If an error occurs during validation, clearly communicate it to the user.
Auto correction – Have the username or email field on the log-in page turn off the auto-correct and auto-capitalize options to reduce the likelihood of entry errors.

Provide clear error descriptions

When account linking fails because a user cannot successfully log in, all related error messages should clearly and concisely communicate the problem and how the user can correct it.

Limit the links

On your log-in page, try to only include links that are pertinent to the account-linking process. This is not the place for users to browse your home page.

Support account recovery

Users often forget their username and/or password for a service. Make sure that you include account recovery options as part of the account-linking experience.

Help your users get help

If your users encounter a problem, such as they forget their password or their account is locked, make sure that it's easy for them to get help. Your log-in page should provide clear guidance on how to contact your user support.

Specifying your authorization URI

Unless you implement app-to-app account linking (starting from the Alexa app), don't use the same authorization URI for the following two items:

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.

Testing account linking

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

Test the account-linking process from a variety of devices and browsers

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

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 few versions of iOS and Android.
Test on different form factors like phones and tablets.
Test with different screen sizes and orientations.

Check that all links on your log-in page work; these will be tested as part of the certification process. Also verify that forward/backward navigation in the browser works, and that you are able to successfully complete the account-linking process after navigating around.

Test the new account flow

Remember that an Alexa skill can help gather new users to your service. This means that if your website or mobile app allows users to create new accounts, your skill should allow it as well. Make sure that you support and test the new-account flow through the skill enablement and account-linking process. If new accounts require any sort of validation, test this in the account-linking flow to make sure that account linking can be accomplished seamlessly, particularly on mobile devices.

Test account recovery

When testing, simulate failed log-in attempts. If multiple failed attempts trigger a CAPTCHA flow or other security mechanism, make sure that these work as part of the account-linking flow, especially on mobile devices. Also be aware of any account states that might interfere with the log-in process. Examples include unverified new accounts, expired subscriptions, or suspended/blocked accounts.

Test multi-factor authentication

If your users can enable multi-factor authentication on their accounts, make sure that the account-linking flow for your skill works with the multi-factor authentication as well.

Token management

Review the following guidelines for best practices for token management. For more details, see Token URI requirements.

Set longer time-to-live values

A longer time-to-live (TTL) value gives more time to your customers to use your skill, which, as a result, reduces the number of customers forced to relink their account due to expired refresh tokens.

Set the refresh token TTL value in the authorization server to 180 days or to never expire. Set the access token TTL value in the authorization server to at least one hour. Similarly, set the expires_in parameter in the access token response to at least 3600 seconds. Make sure that the TTL for access tokens is shorter than the TTL for refresh tokens. Finally, issue a new refresh token, or extend the life of the existing refresh token, every time the authorization server renews the access token.

Don't invalidate old tokens too soon

If the authorization server marks old tokens invalid before Alexa obtains a new token, a race condition can occur during the refresh-token process between Alexa and the authorization server. As a result, customers have to link their Alexa account with your service again.

Configure the authorization server to keep access and refresh tokens valid when generating new tokens. Don't immediately invalidate either the access token or the refresh token during token refresh. Continue to allow old tokens until the server confirms that the Alexa service successfully obtained a new access token along with the most recent refresh token. Finally, make sure that the authorization server doesn't invalidate tokens during software or hardware maintenance.

Miscellaneous

Review the following guidelines for other best practices.

Make sure that you really need account linking

If your skill is not based on a skill type that requires account linking, and you simply need to persist data between sessions, account linking isn't strictly required. The user ID attribute provided with a request from Alexa identifies the same user across sessions unless they disable and re-enable your skill. To save data across multiple skill sessions, you must save the state in a data store that's external to the skill session. Also, if you need information, such as the user's address or location, consider the permission feature instead of account linking. For more details, see Configure Permissions for Customer Information in Your Skill.

Make sure that users can switch accounts

Make sure that users can change the account associated with the skill. For example, if a user disables and re-enables your skill, require them to log in to your service again.

Watch your response header size

To avoid page-loading issues, we have found that it's best to stay under 2,000 characters. Keeping the character account under this value may require eliminating extraneous cookie values unrelated to OAuth account linking.

Redirect the user

When your log-in process is complete, don't forget to redirect the user back to the Alexa app. For example, if you create a branded success or failure page, make sure to include the redirect step, particularly when a user successfully logs in. To successfully redirect the user, make sure to register the Alexa redirect URLs with your authentication provider. You can find the URLs to register in the Alexa Redirect URLs entry in the Account Linking section on the developer portal and in the redirect_uri parameter of the authorization request URL.

Was this page helpful?

Provide feedback

Last updated: Sep 10, 2024