article

Some Alexa skills require the ability to connect the identity of the end user with a user in another system. This is referred to as account linking, since the goal is to create a link between the Alexa user and the user account in your system. Interactions between a user and an Alexa device can include cards displayed in the Amazon Alexa App, the companion app available for Fire OS, Android, iOS, and web browsers. These are graphical cards that describe or enhance the voice interaction. A custom skill can include these cards in its responses. These cards help in guiding the users to complete account linking.

To view the cards, for account linking skills, open the Alexa app and navigate to the Activity page. A LinkAccount card is a special card type only used with account linking. This card lets users start the account linking process. For an ideal user experience, if the user invokes an intent that requires this link and the link has not yet been established, the skill should send back a response directing the user to use the Alexa app to link their account.

Let’s see an example of a good user experience:

User: Alexa, open Bigg basket

Skill: You must authenticate with your Amazon Account to use this skill. I sent instructions for how to do this in your Alexa App.

Let’s see another example now:

User: Alexa, open Urban workforce and get me a plumber.

Skill: This request could not be completed due to pending permissions.

This is a bad user experience as the skill does not inform the users about how to provide the permissions requested by the skill/ why skill requires the permissions. It also provides no help on how to complete these permissions. For display devices, apart from the two points called out previously, the skill should also provide permissions card on either the home page of companion app or to the screen. The user experience can be a good one if the skill responds with the below statement:

Skill: You must authenticate with your Amazon Account to use this skill. I sent instructions for how to do this in your Alexa App.

How to ensure a seamless account linking experience for the customers:

The card displayed in the app is a special card type that lets the user connect their account. The account linking card is available in the main Home feed in the app, in addition to the Activity feed. The card includes the skill icon and name. The "Link Account" button opens the authorization URI that we configure in the developer console when setting up account linking for the skill. When we invoke a skill from a device, the user will receive a card in the Alexa app asking you to link your account and the skill prompt will be like below:

Whenever users invoke intents in the skill that rely on information obtained from account linking, the skill code should return a “LinkAccount” card to be displayed in the Alexa app or the Alexa web site. The card will contain a link allowing the user to authenticate on Login with Amazon. In addition to the card, it is a recommended practice to return a voice prompt inviting the user to authenticate in the app.

Enter the following:

Key	Value
Authorization Grant Type	Auth Code Grant
Authorization URI	https://www.amazon.com/ap/oa This is the URL where Alexa Service will send the customers for authentication. This URL will show customers the Login With Amazon login page.
Access Token URI	https://api.amazon.com/auth/o2/token This is the URI the Alexa Service needs to use to exchange an authorization code for a token and to refresh expired tokens. This is the same value for all Login with Amazon applications.
Client ID	The Client ID received from Login with Amazon during Step 1 above. This has a format such as amzn1-application-oa2-client-xxx
Client Secret	The client secret received from Login With Amazon during Step 1 above.
Scope	Login with Amazon supports several scopes, for this example, let’s use “profile”. This will allow your code to retrieve a unique Amazon userid, email address, and full name for the user.

Below is a quick checklist to ensure a seamless account linking experience for our users. Kindly ensure that you must use your Amazon developer account for these steps:

1. Enable your skill in the Alexa app and start the account linking flow.
2. Test that the skill is successfully linked to the other service. Your Amazon developer account should now be connected with the test account in the other service.
3. When you submit your skill, provide the credentials (account, password and any 2FA related information) for the test account in the Testing Instructions field.
4. Whenever users invoke intents in the skill that rely on information obtained from account linking, the skill code should return a “LinkAccount” card to be displayed in the Alexa app or the Alexa web site. The card will contain a link allowing the user to authenticate on Login with Amazon. In addition to the card, it is a recommended practice to return a voice prompt inviting the user to authenticate in the app.

Happy skill building!