Your Alexa Consoles
Sign In
Sign In

Let Users Enable Your Skill without Account Linking

By default, when a user enables a custom skill that uses account linking in the Alexa app, the account linking flow starts automatically. This can cause friction for users who don't want to link their accounts right away, especially if your skill provides some functionality that does not require authentication. You can change this default behavior to make it easier for users to enable your skill and use functionality that does not require authentication.

Account linking and the user experience in the Alexa app

When a user views your skill in the store and enables your skill in the Alexa app, the experience depends on how you have configured account linking.

Users allowed to enable without account linking Users not allowed to enable without account linking (default)

Skill detail card in the store

The detail card shows that account linking is available for the skill.

Account linking is available, but does not need to be completed when the user enables the skill

The detail card for the skill shows that account linking is required for the skill.

Account linking is required

User enables the skill

The skill is enabled immediately and the user is not presented with account linking flow.

The Alexa app displays your login page to start the normal account linking flow.

User interacts with the skill

The user interacts with the skill normally.

  • Requests that do not require account linking should be fulfilled normally.
  • Requests that do require account linking should tell the user they need to link accounts, and return a link account card .

The user can return the the Alexa app at any time to complete the account linking process. The user can start this process either from the link account card or from the skill detail card.

The user interacts with the skill normally.

  • If the user successfully linked their accounts when the skill was enabled, requests should be fulfilled normally.
  • If the user canceled the account linking process or the process failed, requests should tell the user they need to link accounts, and return a link account card .
The link account card in the Alexa app.
Use the link account card when the user who has not linked their account makes a request that requires authentication

When to let users enable the skill without account linking

Your skill should let users enable the skill without account linking if the skill includes meaningful functionality that does not require the linked account. To encourage users to try your skill even if they do not want to connect their accounts, you may want to explain which features require account linking and which do not in your skill description.

Make sure that your intents that do need account linking return a response that includes both:

  • Text-to-speech explaining that account linking is required for the feature. The text should also direct the user to the Alexa app to link their account.
  • The LinkAccount card.

For example, in this interaction the user made a request that requires an account:

User enables Car Fu and does not start the account linking flow.

User: Alexa, open Car Fu
Alexa: Welcome to Car Fu. I can give you driving directions and traffic reports. If you have a Car Fu account, I can order you a ride. Which will it be?
User: Get me a ride to 123 Main Street.
Alexa: You need a Car Fu account to order a ride. Open your Alexa app and click the link to connect to your Car Fu account.
The skill sends the link account card, as explained in Respond to the User if the Token is Invalid or Missing.

See Respond to the User if the Token is Invalid or Missing.

In this example, the user's request does not require an account, so the skill fulfills the request normally:

User enables Car Fu and does not start the account linking flow.

User: Alexa, open Car Fu
Alexa: Welcome to Car Fu. I can give you driving directions and traffic reports. If you have a Car Fu account, I can order you a ride. Which will it be?
User: Give me a traffic report for Seattle. (This is a general request that does not require a Car Fu account.)
Alexa: As of 9 am today, traffic in Seattle…

If your skill does not have any meaningful functionality without a linked account, turn off Allow users to enable skill without account linking and use the default behavior instead.

Configure your skill to let users enable it without account linking

You can use the developer console, ASK CLI, or Skill Management API to set the Allow users to enable skill without account linking option.

Update a live skill

You can change this option in a previously-published skill. This has no effect on users who have already enabled the skill. It only changes the experience for new users who enable your skill after you make this change. Note that changing this option requires you to re-submit your skill for certification.

To allow users to enable your skill without account linking:

  • Developer console: Navigate to the Build > Account Linking section of the developer console and select the Allow users to enable skill without account linking option.

  • ASK CLI: Use the create-account-linking subcommand and specify YES when prompted to "Allow users to enable skill without account linking". Make sure you have the latest version of the ASK CLI to use this option. You can make sure you have the latest version by running the command:

    $ npm update -g ask-cli
  • Skill Management API: Set the skipOnEnablement option to true in your account linking schema and send an update account linking request.

This example shows an account linking schema configured with skipOnEnablement set to true:

{
  "accountLinkingResponse": {
    "skipOnEnablement": true,
    "accessTokenScheme": "HTTP_BASIC",
    "accessTokenUrl": "https://api.amazon.com/auth/o2/token",
    "authorizationUrl": "https://www.amazon.com/ap/oa",
    "clientId": "amzn1.application-oa2-client.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "domains": [],
    "scopes": [
      "Profile"
    ],
    "type": "AUTH_CODE"
  }
}

Update your code and metadata

Review your intent handlers and make sure they do the following:

  • Intents that do not require account linking handle the user's request directly.
  • Intents that require account linking validate the token and return a link account card if the token is missing or invalid. For a better user experience, save any relevant user data in a persistent data store so that the user can pick up where they left off after they link the account and return to the skill.

Also review your skill store metadata. To encourage users to try your skill even if they do not want to connect their accounts, you may want to explain which features require account linking and which do not in your skill description.

Skill detail card for a skill that can be enabled without account linking
Skill detail card for a skill that can be enabled without account linking