Troubleshooting Account Linking

Having trouble with account linking? The following sections show possible resolutions for common issues.

The sections cover the following types of account linking issues:

General account linking issues

Issue: Account linking is unsuccessful

Symptoms

When attempting to link account, users get the error "We were unable to link at this time" or "Linking unsuccessful."

Try this

For the authorization code grant account linking flow, one of the most common issues is for account linking to fail during the process of exchanging the authorization token for the access and refresh token. When a user starts the account linking process, the Alexa app displays a log-in page, which uses the authorization URI from the account linking configuration in the Alexa developer console.

After your authorization server authenticates the user, the authorization server generates an authorization code. The Alexa service then uses the authorization code in a POST request to retrieve an access and refresh token pair from your authorization server's access token URI. If Alexa can't receive the access and refresh token pair from your authorization server, it displays an error.

You can usually resolve this problem by checking the following items:

  • Check your authorization server logs – More often than not, account linking fails due to an error sent by your authorization server. Check the responses from your authorization server to see what you're sending back to Alexa when your authorization server is presented with the authorization code in exchange for an access/refresh token pair. The following are some areas to check on your authorization server:
    • Check that the authorization server is generating a valid authorization code for the exchange of access and refresh tokens.
    • Log the response from your authorization server to make sure it returns the access token and refresh token in a JSON response to Alexa. Make sure the authorization server isn't sending an error or an invalid JSON response.

    If you're using a third party OAuth server such as Google Sign-In or Facebook Login and you don't have access to the services' logs, you can set up AWS API gateway to get access to additional logs. For instructions on how to set up Amazon API Gateway as a proxy to check the JSON that is being sent to and from the Alexa service, see How to Set up Amazon API Gateway as a Proxy to Debug Account Linking.

  • For smart home skills, check your AcceptGrant response – If you're building a smart home skill and using account linking, you might have enabled the "Send Alexa Events" permissions to send events, such as change report events, to proactively report device states. If the "Send Alexa Events" permissions is on for your smart home skill, you must handle the AcceptGrant directive that is sent to your skill's Lambda function during account linking. Your skill endpoint must respond synchronously with an AcceptGrant.Response to retrieve the authorization code that is used to proactively report states. For details on the AcceptGrant directive, see Directives.

    To test whether this is the cause of the account linking failure, try turning off the "Send Alexa Events" permissions from the Alexa developer console and then test account linking. If account linking works, make sure your Lambda function handles the AcceptGrant directive.

  • Check that your server responds within 4.5 seconds – When your authorization server responds to the access token request, your server must respond within 4.5 seconds. If it doesn't, the request times out and account linking fails. For access token requirements, see Access token URI requirements.

Symptoms

Account linking succeeds, but the customer must link accounts again later.

Try this

This symptom usually indicates that Alexa was unable to use the provided refresh token to get a new access/refresh token pair. Access tokens must have a lifetime of at least six minutes. Set access tokens with a lifetime greater than or equal to six minutes or 360 seconds in the expires_in parameter. Also make sure that the Default Access Token Expiration Time in the Alexa developer console is greater than or equal to 360 seconds. The following example shows an access token response.

HTTP/1.1 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "access_token":"Atza|EXAMPLEACCESSTOKEN123456...",
   "token_type":"bearer",
   "expires_in":360,
   "refresh_token":"Atzr|EXAMPLEREFRESHTOKEN123456X..."
}

Test to see if your authorization server can successfully refresh the access token pair and isn't invalidating refresh tokens before the five-minute window expires. If your authorization server already invalidated the refresh token, Alexa isn't able to refresh the access and refresh token pair and your customer will have to link their account from the Alexa app again.

In summary, check the following items:

  • Ensure that the access token time to live (TTL) is more than five minutes.
  • Ensure that your authorization server can successfully refresh the access/refresh token pair when presented with a refresh token by Alexa.
  • Ensure that you're not invalidating refresh tokens too early.

For access token requirements, see Access token URI requirements.

Issue: Account linking doesn't work on certain devices

Symptoms

Sometimes account linking might work on one device, but not another. In some cases, users might get a blank screen, smartphones open a new window, and so on.

Try this

This symptom might be due to domains missing from the Domain List in the account linking configuration in the Alexa developer console. If your skill's log-in page pulls in any content (such as images) from domains other than your authorization URI's domain, you must add those domains to your skill's configuration. You can add these domains in the Alexa developer console in the Account Linking > Domain List section for your skill.

Make sure you have added all external domains that your account linking log-in page calls or uses. For example, if you make a call to oauth.sample.com, simply adding sample.com isn't adequate; you need to add oauth.sample.com.

Issue: There are issues when account linking with Google

Symptoms

You have issues when account linking with Google.

Try this

As a result of Google's OAuth architecture, the refresh_token is only provided the first time a user authorizes. If you authorize many times on the same account (for example, while testing), that specific account won't return a refresh_token. When the Alexa service requests refresh token, no token is returned. It's also possible that you haven't set access_type=offline when making the query from Google, which means that you're not requesting the refresh token.

To fix a specific account to work with refresh tokens, go to your Google security settings and revoke access from your app. Then, the next time you authenticate, Google treats it as a first-time authentication, and the skill should refresh properly again.

Issue: There's an HTTP 400 error during redirect

Symptoms

When redirected to set up account linking, the user gets an HTTP 400 error.

Try this

This symptom usually indicates that there's something wrong with the redirect_uri, or that the redirect URL is invalid. Alternatively, if the request size is too large (the request size includes the length of the redirect URI, combined with all of the cookies for the domain), the page might not redirect correctly.

Testing in an incognito or private window and confirming that account linking succeeds might confirm this issue. If account linking can complete in an incognito or private window, try reducing the length of the redirect URL or the authorization code. The redirect URL includes all of the query parameters, so reducing the length of these parameters can alleviate the problem.

Account linking still isn't working

Symptoms

You tried the previous solutions and are still having problems linking accounts.

Try this

Review the following important tips and requirements:

  • Pop-ups aren't supported. Attempting to link with a pop-up will fail.
  • For skills that link with implicit grants, the query parameters for sensitive information, such as the account linking token and state, should be included as a URL fragment starting with #. The sensitive information can't be in a query string. An example format is as follows: 
    https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=AAAAAAAAAAAAAA#state=xyz∾cess_token=2YotnFZFEjr1zCsicxLpAA&token_type=Bearer
  • The account linking URL must be an HTTPS URL, with a certificate from an Amazon-approved CA authority.
  • When you send your response with the access token, make sure you send a 200 OK status code.
  • Amazon supports HTTP basic and credentials in the request body as authentication methods. If your service uses another type of authentication, account linking will fail. For more information about client authentication, see Client Password in the OAuth 2.0 specification.
  • For the authentication code type, you must send the access token in JSON by default as per the OAuth2 specification. If the parameter is in the response as a parameter string by default, account linking will fail. For example, GitHub will fail for this reason. Unfortunately, at this time it's impossible to account link with GitHub without some sort of intermediary API gateway.
For more help, contact Amazon

If you followed all of the debugging steps listed previously, either try again at a later time or file a Contact us case with the all of following information:

  • The skill ID.
  • Test credentials for account linking (that is, the account and password for logging into the account linking page).
  • The customer ID of the account that failed. You can find your customer ID at https://developer.amazon.com/mycid.html.
  • The exact time and date (in UTC, or with the time zone) you tried and failed to link the skill. Provide the most recent timestamp you have, preferably a timestamp within the last 14 days.
  • The region(s) you're trying to link with (for example, EU, NA, Asia, and so on).
  • Device/type platform (for example, Android or iOS).
  • Version of the Alexa app. You can find the version in the Alexa app under Settings > About the Alexa app.
  • Description or a link to a screenshot of the issue. For example, are you seeing an empty page, getting an 'unable to link' page, or finding that a button on the page isn't working?
  • The following account linking configuration from the Alexa developer console Account Linking tab:
    • Authorization URL
    • Domains list
    • Account linking type (implicit grant or authorization code grant)

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

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) issues

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.

Child-directed skill issues

Issue: After adding account linking, my child-directed skill doesn't show up in the Parent Dashboard

Symptoms

I added account linking to my child-directed skill, and now the skill doesn't appear on the Parent Dashboard.

Try this

This behavior is as designed. Child-directed skills aren't allowed to use account linking. Non-child-directed skills that add account linking don't appear in the Parent Dashboard and aren't accessible by child-enabled devices.

Was this page helpful?

Last updated: Jun 27, 2024