Account Linking FAQ

The following frequently asked questions (FAQ) answer common questions about account linking.

General account linking

Q: What are the requirements for my authorization server?

Your authorization server must use HTTPS with a certificate from an Amazon-approved certificate authority. For the authorization code grant, your server must return the access token and refresh token in a JSON response, and must respond within 4.5 seconds. Access tokens must have a lifetime of at least six minutes (360 seconds). For details, see Requirements for Account Linking for Alexa Skills.

Q: Can I make account linking optional for my skill?

Yes. You can configure account linking as optional in custom skills so that users can enable your skill and use features that don't require authentication. When the user invokes a feature that requires account linking, your skill can send an account linking card to prompt the user to link their account. To learn which skill types require account linking, see When to use account linking.

Q: What happens when a user disables my skill?

When a user disables your skill, the account is unlinked. Alexa deletes the access token that your service provided and revokes the Amazon access token. You should also revoke your access token and delete any stored Amazon access tokens for the user. To get notified, subscribe to skill disabled events.

Standard account linking

The following are frequently asked questions about the standard account linking flow from the Alexa app to your website.

Q: What OAuth 2.0 grant types does standard account linking support?

Standard account linking supports both the authorization code grant and the implicit grant. Amazon recommends the authorization code grant because it provides a refresh token, which allows Alexa to obtain new access tokens without requiring the user to re-authenticate. Only custom skills can use the implicit grant type. For details, see Grant types.

Q: How does a user link their account through the standard flow?

In the standard flow, the user starts from the Alexa app. When the user enables the skill or taps "Link Account" from the skill settings, the Alexa app opens your authorization URI in an in-app browser. For details, see Users Experience Account Linking.

Q: What are the design requirements for my login page?

Because the Alexa app opens your login page in an in-app browser, your page must be mobile-friendly. Your login page must not open pop-up windows or launch JavaScript alerts or message boxes. If the user encounters an error, such as entering the wrong password, the login page should display the error inline. For details, see Design the log-in page.

App-to-app account linking starting from your app

The following are frequently asked questions about the app-to-app account linking flow that starts from your app.

Q: How do I know if the Alexa app isn't installed on the user's mobile device?

For an example of how to determine this in iOS, see Example: Open the URLs in Step 4: Make an Authorization Request from Your App.

Q: I own more than one skill. Can I link accounts for all the skills at one time?

To protect user trust, app-to-app account linking requires user consent for a specific skill. If you want to link a user's account for more than one Alexa skill, you must take the user through the linking flow for each skill.

Q: How do I check if the skill is already enabled and the account is already linked?

You make a Get account linking and skill status request to the Alexa Skill Enablement API. When you call this API, you must use one of the following access tokens:

  • The token that you received when you set up app-to-app account linking for the customer.
  • (Smart home skills only) The token that you received from the AcceptGrant directive after mutual authentication.
Q: What if the skill is already enabled and the account is already linked?

When you make an Enable skill and account link request to the Alexa Skill Enablement API, the user's account is relinked and you receive a HTTP 201 Created response.

Q: How can I get notified when account linking is complete?

You can subscribe to the Account Linked event.

Q: What if a user wants to link Alexa with a different user account than the account that they're currently logged in with in your app?

If a user wants to link Alexa with a different account, they should first log in to your app with the other account and then start account linking from within your app. Your app can choose to provide an option to switch accounts within the account-linking flow.

Q: What if a user isn't an existing Alexa user and they don't have the Alexa app installed?

If a user has an Amazon account but isn't an Alexa user, they can sign in to the LWA page with their Amazon credentials and then acknowledge the linking request. If a user doesn't have an Amazon account, they can create a new Amazon account on the LWA screen and complete account linking for the skill. To use Alexa features, the user needs an Alexa-enabled device or Alexa app.

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. You can disable the skill and unlink the account for the user by making a Disable skill and unlink account request to the Alexa Skill Enablement API.

Q: What happens when a user disables my skill? Am I notified?

To get notified when a user disables your skill, you can subscribe to skill disabled events. When the skill is disabled, you should revoke your access token and delete the Amazon access token for the user. Alexa also deletes the access token that your service provided, and revokes the Amazon access token.

Q: What if my skill requires permissions? Can I get these during app-to-app account linking?

Permissions (such as device address and user profile information) are currently not part of this account linking flow. When the user invokes the skill with an intent that needs permissions, you must prompt the user, through a permissions card, for the respective permissions during runtime.

However, when a user links their account through the Alexa-initiated app-to-app account linking flow, they're prompted to grant permissions. You can grant the required permissions by using that flow.

Q: How do I retrieve a user's authorization code for their account in my service?

You must generate the user's authorization code by using your authorization server. In the traditional account linking flow, the OAuth server generates the authorization code when the user logs in to your service and provides consent to link with Alexa. In App-Initiated App-to-App Account Linking where the user is already logged in, you programmatically generate a new authorization code for the user from your OAuth provider. You must not require the user to log in and provide consent again.

App-to-app account linking starting from the Alexa app

The following are frequently asked questions about app-to-app account linking from the Alexa app.

Q: I have multiple apps that can handle account linking requests. How should I set up the app-to-app account linking flow?

Your authorization URIs must be able to open different apps. Each platform handles this differently as follows:

  • iOS – Add the domain of the authorization URI to the entitlements file of every app that can handle the account linking request. In the Apple App Association File of the domain, add a separate 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 – Add the domain of the authorization URI to the app manifest of every app that can handle the account linking request. In the Asset Links JSON of the domain, add a separate entry for each app. If a user has more than one of the apps installed, the Intent Filter Priority in your app manifest determines the preference.

Q: Can I use the same app if I have multiple skills?

Yes. You can either use the same authorization URI for every skill or configure separate authorization URIs for each skill and enable Universal Links or App Links for each one.

Q: What if a user wants to link Alexa with a different user account than the account they're currently using?

You can enable users to log out and choose a different account when they receive the linking request 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 requiring the user to log in again.

Q: Can users do device discovery after linking their accounts?

Yes. The post-linking experience is the same as in the standard account linking flow.

Q: Can users consent to skill permissions?

Yes. Users can grant skill permissions before linking their accounts.

Q: Can users link their personal accounts for skills that work with skill personalization?

Yes. The app-to-app account linking flow supports linking personal accounts.

Q: How do I know the user's Alexa app supports the app-to-app account linking flow?

The Alexa app sends requests to your app when the user has a version of the Alexa app that supports the app-to-app account linking flow.

Q: How does a user revoke account linking?

Disabling the skill unlinks the account. Users can say, "Alexa, disable <skill name>" or disable the skill from the 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, your Lambda function must handle the AcceptGrant directive. If it doesn't handle the directive, account linking fails when the user attempts to enable your skill. For details, see Request Access to the Alexa Event Gateway.

Was this page helpful?

Last updated: frontmatter-missing