Troubleshooting App-to-App Account Linking

Having trouble with app-to-app account linking? The following sections show possible resolutions for common issues. The sections cover issues with app-to-app account linking (starting from your app) and app-to-app account linking (starting from the Alexa app).

App-to-app account linking (starting from your app)

Issue: "400 Bad Request" error

Symptoms

You receive a 400 Bad Request error when you call the skill enablement API.

Try this

This error can occur when the format of your request to the skill enablement API is incorrect. If you get this error, check the following settings:

  • Ensure that you use title case for Bearer in the authorization parameter. For details and an example request for each API operation, see Skill Enablement REST API Reference.
  • As with all skill management APIs, ensure that you get an access token for the customer before calling the skill enablement API.

Issue: "401 Unauthorized" error

Symptoms

You receive a 401 Unauthorized error when you call the skill enablement API.

Try this

This error can occur when the enablement for the skill and the user was deleted. If you're not aware when users disable your skill, you end up with invalid tokens.

To prevent this issue, monitor the skill-disabled event and delete the tokens for disabled skills. This way, you don't call the skill enablement API for scenarios when the token has been revoked. For details about the skill disabled event, see Skill Disabled Event.

Issue: "403 Forbidden" error

Symptoms

You receive a 403 Forbidden error when you call the skill enablement API.

Try this

This issue can have the following causes:

  • The client ID doesn't have permission to request the account linking scope.
  • You request an operation for a development-stage skill from an account that doesn't have permission to call the skill enablement API. Only the developer account used to create the skill and any accounts you manually add as beta testing accounts can request operations.

Depending on the cause, try the following solutions.

Solution 1

To make sure the client ID has permission to request the account linking scope, perform the following steps:

  1. Sign in to the Alexa developer console and navigate to your skill.
  2. Select the Build tab.
  3. On the left, click TOOLS, and then click Account linking.
  4. Add your app's redirect URLs.
    By adding your app's redirect URLs, you're giving the client ID permission for the alexa::skills:account_linking scope.

For details, see URLs and endpoints, FAQ, Skill Enablement REST API Reference.

You can also perform this task by using Alexa Skills Kit Command Line Interface (ASK CLI) or the Alexa Skill Management API (SMAPI).

Solution 2

Add the desired account to the skill's beta pool. For details, see Skill Beta Testing for Alexa Skills.

Issue: "Invalid account linking credentials" error

Symptoms

You receive an Invalid account linking credentials error when you call the skill enablement API.

Try this

This error can occur when you use an unsupported OAuth 2.0 server.

To complete your account linking configuration, you must implement a full authentication server. Otherwise, Alexa fails to exchange the authorization code for an access token for the user. Implementing default account linking (starting from the Alexa app) is a part of implementing the app-to-app account linking flow. For details, see Implement Account Linking in Your Skill.

Issue: "Could not contact provider of account linking credentials" error

Symptoms

You receive a Could not contact provider of account linking credentials error when you call the skill enablement API.

Try this

This error can occur when Alexa can't connect to your token exchange server.

Review the logs of your token exchange server and verify that the request was successfully received. If an error occurred, identify the root cause from your logs.

Issue: Account linking doesn't complete

Symptoms

After the app-to-app account linking flow, the skill isn't enabled and the account isn't linked for the user.

Try this

This issue can occur when you don't call the skill enablement API to create the enablement with the account link.

Look into your logs to make sure that the call to the skill enablement API is happening as part of the app-to-app (starting from your app) flow to complete account linking. For details, see Enable skill and account link.

Issue: The Login with Amazon (LWA) fallback flow doesn't work

Symptoms

You receive an error when you try to complete the LWA fallback flow.

Try this

This issue can occur for the following reasons:

  • Your skill is using an incorrect configuration when it opens the LWA fallback URL to get the user's Amazon authorization code.
  • You haven't set up the LWA fallback flow correctly.
  • The redirect URL is opened in the default browser of the user.

Depending on the cause, try the following solutions.

Solution 1

Check the URL and the query parameters that you use when you open the LWA fallback URL. The provided redirectURL should be the URL of your app, so that when the user acknowledges the account linking request, they are redirected back to your app. For details, see Parameters for the Alexa app URL and the LWA fallback URL, and URLs and endpoints.

Solution 2

Check the following parameters in your LWA fallback flow. There are two pairs of client IDs and secrets available to you in this scenario, and you can't use the same security profile (client ID and secret) in both cases:

  • Client ID/secret from Alexa – This client ID/secret pair isn't editable by you when your skill opts in to use app-to-app account linking (starting from your app). These values show up in the Account Linking section of the Alexa developer console. This is the client ID and secret that you use to get the user's consent and access token from LWA, which you can then use to call the skill enablement API to enable and link the skill.
  • Client ID/secret from you – You provide this information for your own authorization and token servers (this could also be LWA, but even in this scenario, the client ID and secret are different than the client ID and secret described previously) in the developer console account linking page. In the case of app-to-app account linking (starting from your app), use your own authorization server to generate the user's authorization code, which you send in the request to the skill enablement API.

Solution 3

Consider whether the redirect URL is opened in the default browser of the user, which is undesired behavior. This scenario can happen for the following reasons:

  • Universal Links or App Links aren't enabled in your app.
  • The version of the app on the user's device is an older version that doesn't support Universal Links or App Links.
  • Universal Links or App Links aren't enabled in your app for the redirect URLs that you provided.

Verify which scenario the issue falls under. The first two scenarios are actionable only by the user, but you can address the third scenario. For details, see Enable Universal Links (iOS) or App Links (Android) for your app.

Issue: On Android, account linking fails when the user selects the default browser app to open the Alexa app

Symptoms

On Android, the user sees the "use a different app" selector when they open the Alexa app during the app-to-app account linking (starting from your app) flow, so they select their default browser. Account linking then fails.

Try this

The user shouldn't be able to open the Alexa app by using the default browser because the Android Alexa app has Android App Links enabled, which requires links to be opened in a specific app.

If a user sees the "use a different app" selector, the user's Alexa app has invalid App Links. This situation can happen when the Alexa App isn't able to fetch the corresponding assetlinks.json file for all the domains specific in the Android manifest during the app's installation. This edge case is a known issue with Android App Links, and the user can fix this by deleting and re-installing the Alexa app.

Issue: You're unable to target non-account-linked users to "Link to Alexa" from within your app

Symptoms

You're unable to target users who aren't yet account-linked to "Link to Alexa" from within your app.

Try this

This issue can occur if you implement app-to-app account linking after the initial release of your skill. In this case, you might have existing account-linked users who completed the setup through the traditional account-linking flow in the Alexa app. App-to-app account linking (starting from your app) can't selectively target users who aren't yet account linked.

You can achieve selective targeting by subscribing to skill events (SKILL_ACCOUNT_LINKED and SKILL_DISABLED). Skill events notify you of the latest account-linking status for your users. For details, see Skill Events in Alexa Skills.

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

Issue: On Android, your web URL is opened instead of your app

Symptoms

On Android, your web URL is opened instead of your app.

Try this

This issue can occur if App Links aren't correctly set up for your app on the user's phone.

Verify the following aspects of your Android App Link implementation:

  • Confirm that App Links are enabled in your app by enabling the autoVerify flag in the app manifest.
  • Verify that all the domains listed in the app manifest pass the Android App Links validation.
  • Verify that all domains listed in the app manifest should host the assetlinks.json file.

For details, see Verify Android App Links, Check link policies, and Android App Links verification in the Android documentation.

Issue: On Android, when your app isn't installed, the Android App Authorization URI is opened instead of the expected Web Authorization URI

Symptoms

On Android, when your app isn't installed, the Android App Authorization URI is opened instead of the expected Web Authorization URI.

Try this

This is the expected behavior, so you don't need to take action. This issue is relevant when your app isn't installed on Android. In this scenario, the URL used in the in-app browser is your Android App Authorization URI and not the expected Web Authorization URI.

On Android, when the user doesn't have your app installed, Alexa uses the value of the "Your Android App Authorization URI" field as the fallback authorization URI. In iOS, Alexa uses the value of the "Your Web Authorization URI" field as the fallback authorization URI when the user doesn't have your app installed. The different behavior between the two platforms is due to iOS's constraint that an external link can't be opened in the Alexa app. For this reason, Alexa uses the Web Authorization URL for iOS. Android, on the other hand, doesn't have this restriction.

Issue: The account linking completion rate for app-to-app account linking is incorrect

Symptoms

The account linking completion rate for app-to-app account linking (starting from the Alexa app) is incorrect.

Try this

Successful completions of the app-to-app account linking (starting from the Alexa app) flow depend on your app redirecting back to the Alexa app.

Ensure that you append the query parameter source=app to your authorization response when you redirect the user to the Alexa app. For details, see Step 4: Redirect the user to the Alexa app.