Account Linking for Smart Home and Other Domains

All smart home and video skills must connect the identity of the Alexa user with an identity in the service provider's system. This is known as account linking, because the goal is to create a link between the Alexa user and the service provider.

Not all music skills support account linking, but for those that do, users must perform account linking as described in this topic.

How Users Connect their Accounts to a Smart Home, Video, or Music Skill

For smart home and video skills, and for music skills that support account linking, the skill detail card indicates that account linking is required.

  1. In the Alexa app, the user clicks Enable to start the account linking process.
  2. The app displays a login page for your service provider system.
  3. The user enters their credentials in the login page and authenticates with your service.
  4. The user is redirected back to a "success" page within Alexa app.

When the account linking succeeds, Alexa stores an access token that identifies the user in the service provider. Alexa includes this token in all requests to the skill, so the skill can access the user's information in the service provider system when the user invokes the skill.

Prerequisites

Your system must have OAuth 2.0 enabled and support the authorization code grant flow type.

If you have not implemented OAuth 2.0, you can use Login with Amazon (LWA) as your OAuth 2.0 provider or any provider that has a certificate signed by an Amazon-approved certificate authority. The Amazon-approved certificate authorities includes the certificate list here. Note that you cannot use https://letsencrypt.org/, even though it is on the certificate list.

In addition, access tokens provided by your system must have a lifetime of at least 6 minutes. This means the expires_in parameter of your access token response must be greater or equal to 360.

Configure Account Linking

You configure your skill with account linking in the developer console in the Build > Account Linking section.

For details about the account linking configuration fields, access tokens, and the overall authorization code grant flow, see Configure Authorization Code Grant.

Update your Skill code with Account Linking Logic

Each directive sent to your skill includes the access token to identify the user. Your Lambda function needs to validate the token, then use it to access information about the user. See Validate and Use Access Tokens in Smart Home and Video Skill Code.

In addition, if you enable the Send Alexa Events permission for the skill, your Lambda function must handle the AcceptGrant directive. If your skill does not handle this directive, account linking fails when the user attempts to enable your skill. See Authenticate a Customer to Alexa with Permissions

OAuth Resources:

Other Resources: