Let Users Enable Your Skill without Account Linking

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

By default, users can enable a skill without starting the account linking flow. This reduces friction for users when they enable your skill and makes it easier for them to use the parts of the skill that do not require authentication. Alternatively, you can require users to link their accounts when they enable the skill, but this does add more friction to the process.

Account linking and the user experience in the Alexa app
When to let users enable the skill without account linking
Configure your skill to require or not require account linking
Update your code and metadata
Related topics

Account linking and the user experience in the Alexa app

When a user views your skill in the Alexa Skills 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 (default)	Users not allowed to enable without account linking
Skill detail card in the store	The detail card shows that account linking is available for the skill.	The detail card for the skill shows that account linking is required for the skill.
User enables the skill	The skill is enabled immediately and the user is not presented with account linking flow.	The Alexa app displays your log-in 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 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.

Skill detail card in the store

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

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

User enables the skill

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

The Alexa app displays your log-in 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 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.

Important: All custom skills that use any form of account linking need to handle requests that do not include a valid access token. This is true even if account linking is required for all intents in your skill. If the user enables the skill by voice, cancels the account linking process, or encounters an error during the process, the skill is still enabled. Requests sent to your skill in this case do not include the access token. For more about checking tokens and responding to requests, see Validate and Use Access Tokens in Custom Skill Code.

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 Ride Hailer and does not start the account linking flow. User: Alexa, open Ride Hailer

Alexa: Welcome to Ride Hailer. I can give you driving directions and traffic reports. If you have a Ride Hailer account, I can order you a ride. Which will it be?
User: Get me a ride to 123 Main Street.

Alexa: You need a Ride Hailer account to order a ride. Open your Alexa app and click the link to connect to your Ride Hailer 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 Ride Hailer and does not start the account linking flow. User: Alexa, open Ride Hailer

Alexa: Welcome to Ride Hailer. I can give you driving directions and traffic reports. If you have a Ride Hailer 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 Ride Hailer 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. Users are then sent into the account linking flow when they enable the skill.

Configure your skill to require or not require 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.

Note: By default, this option is turned on when you initially enable account linking for skill.

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 TOOLS > 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",
    "voiceForwardAccountLinking": "DISABLED"        
  }
}

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

Was this page helpful?

Provide feedback

Last updated: Sep 10, 2024