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
- Configure Account Linking
- Update your Skill code with Account Linking Logic
- Related Topics
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.
- In the Alexa app, the user clicks Enable to start the account linking process.
- The app displays a login page for your service provider system.
- The user enters their credentials in the login page and authenticates with your service.
- 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.
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
- Understand Account Linking
- Configure Authorization Code Grant
- Validate and Use Access Tokens in Smart Home and Video Skill Code
- 10 Tips for Successfully Adding Account Linking to Your Alexa Skill
- Beyond the Basics: Best Practices for Adding Account Linking to Your Alexa Skills
- Alexa Account Linking: 5 Steps to Seamlessly Link Your Alexa Skill with Login with Amazon
- How to Set up Amazon API Gateway as a Proxy to Debug Account Linking
- Debugging Account Linking KB Article