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.

For an explanation of account linking concepts, see Account Linking Concepts for Alexa Skills. For the user experience, see How Users Experience Account Linking for Alexa Skills.

Prerequisites

To implement account linking for smart home skills, you must have the following prerequisites:

  • Your system must support OAuth 2.0 and the authorization code grant type.

    If you do not have your own authorization server, you can use Login with Amazon (LWA) or any OAuth 2.0 provider that has a certificate signed by an Amazon-approved certificate authority. Note that you cannot use https://letsencrypt.org/, even though it is on the certificate list.
  • Access tokens that your system provides must have a lifetime of at least 6 minutes. This means that the expires_in parameter of your access token response must be greater than or equal to 360.

For other requirements, see Requirements for Account Linking for Alexa Skills.

Configure account linking

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

For details about the account linking configuration fields, access tokens, and the overall authorization code grant flow, see Configure an 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 the following topics:

In addition, if you enable the Send Alexa Events permission for the skill, your Lambda function must handle the AcceptGrant directive. If your skill doesn't handle this directive, account linking fails when the user attempts to enable your skill. For details, see Request Access to the Alexa Event Gateway.

Automated registration

Your skill can allow users to register with your system and then link that identity with their Alexa identity during device setup automatically. This is called automated registration.

Automated registration is currently in preview for smart home skills. To receive updates about this feature, sign up using the Automated Registration Interest Form.

Last updated: Apr 19, 2022