Step 4: Set up Account Linking

Now that you've configured the endpoint for your skill, you're ready to set up account linking. All smart home skills must enable account linking to connect the identity of the Alexa user with the user's identity in your system. For a light bulb, your system might have a user account that store's the light bulb model and capabilities, such as whether you can dim the bulb. When the user enables your skill in the Alexa app, Alexa starts the account linking process and receives an access token from your system. Later, when the user asks Alexa to dim the light bulb, Alexa sends the access token to your skill. The token enables your skill to access the user's account in your system to know whether their light bulb is dimmable.

For simplicity, this tutorial uses the Amazon authorization server, called Login with Amazon (LWA). When you build smart home skills, you can use LWA or your own OAuth 2.0 provider. Alexa uses authorization code grant type for smart home skills.

Substeps to set up account linking

To enable account linking, complete the following substeps.

  1. Create a security profile
  2. Configure account linking
  3. Add redirect URLs to your security profile

Substep a: Create a security profile

In this substep, you create a security profile for your smart home skill on the Amazon authorization server.

To create a security profile in the Login with Amazon console

  1. Sign in to the Login with Amazon console with your Amazon developer account.
  2. On the Login with Amazon page, click Create a New Security Profile.
  3. For Security Profile Name, enter my-smart-home-skill-profile.
  4. For Security Profile Description, enter a description of your product.
  5. For Consent Privacy Notice URL, enter the URL of your company privacy policy to display to the user.
  6. For Consent Logo Image, upload your product logo to display with your privacy policy.
    For this tutorial, you can ignore this field.
  7. To create the new security profile, select Save.
    After Amazon creates the new security profile, your profile has a Client ID and Client Secret credentials.
  8. To view the credentials, next to the profile name that you just created, click Show Client ID and Client Secret.
  9. Copy your client ID and Client Secret to use in the skill configuration.
    Be careful not to copy any additional characters or whitespace.
  10. Paste these values in a convenient place, such as Notepad on Windows or TextEdit on Mac.
    You use these values in the next substep.

In this substep, you configure the authorization server and security profile for the skill in the Alexa developer console.

To configure account linking in the Alexa developer console

  1. Navigate back to your skill in the Alexa developer console.
    If you closed the skill page, follow these steps to find your skill.
    1. Sign in to the Alexa developer console.
    2. On the Skills tab, under SKILL NAME, find the my-smart-home-skill skill that you created in Step 1: Create a Smart Home Skill.
    3. Under ACTIONS, from the drop-down menu in your skill's row, select Edit.
  2. On the Smart Home page, under 3. Account Linking, click Setup Account Linking.
    Or, from the left menu, click ACCOUNT LINKING.
  3. Under Security Provider Information, for Auth Code Grant, provide the following information:
    1. For Your Web Authorization URI, enter https://www.amazon.com/ap/oa.
      Alexa uses this URI to initiate account linking.
    2. For Access Token URI, enter https://api.amazon.com/auth/o2/token.
    3. For Your Client ID, paste the client ID from your security profile.
    4. For Your Secret, paste the client secret from your security profile.
    5. For Your Authentication Scheme, select HTTP basic (Recommended).
    6. For Scope, click +Add scope, and then enter profile:user_id.
    7. To save the data, click Save.
    8. Navigate to the bottom of the page, and then copy the Alexa Redirect URLs.
    9. In a convenient place, such as Notepad on Windows or TextEdit on Mac, paste the URLs. You use these values in the next step.

Substep c: Add redirect URLs to your security profile

In this substep, you add the redirect URLs to your security profile. After the authorization service completes user authentication, the service redirects the user back to the Alexa app. Alexa sends one of the configured redirect URLs to the authorization service in the account linking request.

To add redirect URLs to your security profile in the Amazon developer console

  1. In the Login with Amazon console, navigate back to your security profile.
    If you closed the page, sign-in to the Login with Amazon console.
  2. Find the my-smart-home-skill-profile security profile.
  3. Under Manage, click the gear icon, and then select Web Settings.
  4. On the Security Profile Management, on the bottom right, click Edit.
  5. For Allowed Return URLs, click Add Another twice, and then paste the Alexa redirect URLs that you copied from the Alexa developer console.
  6. To save the profile, click Save.

Success!

You've configured account linking and completed skill configuration. In Step 5, you test your skill code and turn on the virtual light bulb.