Account Linking for Baby Activity Skills

All baby activity skills must use account linking. You must link Alexa customers that use your skill to your app customers by using account linking and profile reports. For more information about account linking, see Understand Account Linking.

You can't create baby activity skills unless you already store customer data and identifiers yourself. Your customers create their profiles in your app, and you create an identifier to track them in your app. When a customer enables your Alexa.Health skill, you send a profile report to Alexa, and send the same identifier to Alexa. Some apps and websites might allow a single customer to manage multiple profiles. For more information, see User Profiles.

Prerequisites for your authorization server

You can use your own authorization server, or an authorization server owned by a third party, such as Login with Amazon. In either case, your authorization server must meet the following requirements:

  • Your authorization server must support OAuth 2.0.
  • Your authorization server must support the authorization code grant type.
  • Your authorization server must have an authorization URL for accepting authorization requests.
  • Your authorization server must have an access token URL for exchanging authorization codes for access tokens.
  • Your resource server must have a reciprocal access token URL for exchanging authorization codes for access tokens.

In addition to your authorization server, your skill must use Login with Amazon (LWA) to obtain access tokens as explained in the sections following. For general information about LWA, see Login with Amazon Documentation.

Sample code

For sample code and instructions on how to set up an authorization server, mutual account linking, and a resource server to support the reciprocal access token exchange, see Create a Consistent Customer Experience with Mutual Account Linking for Your Alexa Skill on the Alexa blog.

Overview of the account linking workflow

After all configuration is complete as explained in the following sections, the following sequence of steps describes what happens when your customer enables your skill. Details are described later in this document.

  1. An Alexa customer clicks Enable on the page for your skill in the Alexa Skills Store.

  2. The customer is directed to the authorization URL for your authorization server and is asked to enter their credentials for your app.

    • After you verify your customer's credentials, the authorization server redirects the customer to the Alexa endpoint for your skill.

    • The authorization server provides Alexa with an authorization code.

  3. Alexa invokes the access token URL, provides the authorization code, and receives an access token/refresh token pair. Later, Alexa uses this access token/refresh token pair when it sends directives to your skill.

  4. Alexa invokes the reciprocal access token URL and provides your skill with an authorization code. An example reciprocal access token URL might look like https://yourserver.com/accepttoken.

  5. You invoke the LWA URL, provide the authorization code, and receive an access token/refresh token pair for the customer.

  6. You send a profile report to Alexa using the access token/refresh token pair for the customer.

You can also enable users to initiate account linking from within your app. For more information, see App-to-App Account Linking.

Configure account linking

You must configure account linking for your skill, otherwise customers can't enable or use your skill.

To configure account linking:

  1. Sign in to the ASK developer console.

  2. Click the name of your skill.

  3. On the left side of the page, click Account Linking.

  4. Choose Auth Code Grant, and enter your security-provider information into the form.

  5. Click Save.

Configure permissions to send profile reports

You must configure permissions to send profile reports from your skill to Alexa.

To configure permissions

  1. Sign in to the ASK developer console.

  2. Click the name of your skill.

  3. On the left side of the page, click Permissions.

  4. Turn on the Send Alexa Profiles toggle.

Provide access tokens to Alexa

After the customer provides their credentials, your authorization server gives Alexa an authorization code. Then Alexa invokes your access token URL. Your authorization server must verify the authorization code that Alexa sends, and give Alexa an access token/refresh token pair.

Obtain your access tokens from Alexa

Step 1: Get your authorization code from Alexa

Alexa invokes your reciprocal access token URL, and provides you with an authorization code.

Alexa invokes the reciprocal access token URL by secure HTTP POST. Alexa provides the following parameters.

Parameter Description
grant_type reciprocal_authorization_code
code The authorization code from Alexa.
client_id The client id.

Example request from Alexa

POST
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer <access_token>
grant_type=reciprocal_authorization_code
&code=<authorization_code>
&client_id=<client_id>

Verify the access token specified in the authorization header by doing the following:

  • Verify that the access token was granted to the client identified by the client_id.
  • If the verification fails, return HTTP 403 (FORBIDDEN).

Step 2: Obtain your access tokens from LWA

You must use Login with Amazon (LWA) to exchange your authorization code for an access token/refresh token pair. You invoke the LWA URL, provide the authorization code, and receive an access token/refresh token pair for the customer.

Send an access token request to LWA at https://api.amazon.com/auth/o2/token by using a secure HTTP POST. Provide the following parameters.

Parameter Description
grant_type authorization_code
code The authorization code that Alexa gave you.
client_id The client id. Get this from the permissions section in the developer console.
client_secret The client secret. Get this from the permissions section in the developer console.

After you send your request to LWA, do the following:

  • If your request is successful, LWA responds with an access token/refresh token pair.
  • Store your access token/refresh token pair along with your identifier for the Alexa customer.
  • If this step fails, return a HTTP 400 (BAD_REQUEST).

If all steps succeed, return HTTP 200 (OK). Return HTTP 500 (INTERNAL_SERVER_ERROR) if anything goes wrong not covered by a previous error case.

Send a profile report to Alexa

Send a profile report the first time an Alexa customer enables your skill, after the account linking steps are complete. If a customer adds, updates, or deletes a profile in your app, send a new profile report to Alexa.

After you obtain the access token/refresh token pair for a customer, post the profile report to api.amazonalexa.com/v1/health/profile. The header of the request contains the access token, which allows Alexa to match the Alexa customer to your app customer profiles identified in the profile report. For the format of the body of the profile report, see User Profiles.

Example profile report header

Authorization: Bearer <access_token>
Content-Type: application/json

Account linking schema for the ASK CLI

In addition to the developer console, you can also use the Alexa Skills Kit Command Line Interface (ASK CLI) to create and manage skills from the command line. For more information about the ASK CLI, see Quick Start: ASK CLI. For more information about account linking with the ASK CLI, see Account Linking Management.

If you use the ASK CLI to manage your baby activity skill, your account linking schema must include the reciprocalAccessTokenUrl field and the scopes field must include profile.

Example baby activity skill account linking schema

{
    "accountLinkingRequest": { 
        "type":"AUTH_CODE",
        "authorizationUrl":"<https_URL>",
        "clientId":"<client_id>", 
        "scopes":[
            "profile"
        ], 
        "accessTokenUrl":"<https_URL>",
        "clientSecret":"<client_secret>", 
        "accessTokenScheme":"HTTP_BASIC", 
        "reciprocalAccessTokenUrl":"<https_URL>"
    }
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment