Configure an Implicit Grant

The Alexa Skills Kit supports implicit grants for account linking in custom skills. You can’t use this grant type for other types of skills, such as smart home add-ons.

Implicit grant flow overview

Alexa uses the OAuth 2.0 account linking flow with implicit grant to link the user’s Amazon account with their account in your system. This flow is the same for both traditional account linking and app-to-app account linking starting from the Alexa app. In traditional account linking, Alexa uses the configured URI to open the login page on your website. In app-to-app account linking, Alexa uses the configured URI to open the login page in your app, or if the app isn’t installed on the device, Alexa uses the website URI as fall back. Users can start the account linking process when enabling the skill or from a link account card in the Alexa app. For more about how users interact with account linking, see Account Linking for Custom Skills.

Link the account

The following steps describe implicit grant flow to link the user accounts.

The user starts the process by enabling the skill in the Alexa app or tapping a link on the link account card.
The Alexa app displays a login page within the app, using the authorization URI you provide when you configure account linking. This login page lets the user authenticate with the authorization server. When the Alexa app calls the specified authorization URI, it includes state, client_id, response_type, scope, and redirect_uri as query string parameters.
The user logs in using their credentials for the authorization server.
Once the user is authenticated, the authorization server generates an access token (access_token) that uniquely identifies the user.
The authorization server redirects the user to the specified redirect_uri and passes along the state, access_token, and token_type in the URL fragment.
The Alexa service saves the access_token for the Alexa user.

The user’s Alexa account is now linked to the account in your service, and the skill is ready for use. The following diagram shows the account linking flow when the user links their account from the Alexa app. Here, Alexa obtains the access token from your authorization server as described in steps 1–6.

Use the access token in your skill

When the user makes requests to the skill, each request, such as an IntentRequest, now includes the access_token. Your skill uses this token to get the information you need from the resource server. The following diagram shows the flow when the user makes a request to the skill and the skill then uses the access token to retrieve information from the resource server.

Skill uses the access token to request user resources. — Access token in skill interaction

Authorization URI details

You configure the authorization URL in the Alexa developer console on the Build > Account Linking page. You provide the URL in the Authorization URI field. The Alexa service passes parameters to your authorization server in the URL query string. For example, if the authorization URI for your page is https://www.ridehailer.com/login, Alexa sends the following parameters:

https://www.ridehailer.com/login?state=abc&client_id=unique-id&scope=order_car+basic_profile&response_type=token&redirect_uri=https://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA

The Alexa service includes the following parameters in the query string when it opens your authorization URI.

Alexa redirect URLs details

You can find the redirection endpoints for the Alexa app in the Alexa Redirect URLs field on the Build > Account Linking page in the developer portal. These endpoints are the URLs to which your log-in page must redirect the user after the user authenticates with your server. The list shows multiple URLs, one for each Alexa region. Based on where the user registered their device, the Alexa app selects and passes the redirect URL with your authorization URI in the redirect_uri query parameter in the URL query string. Your server must use the redirect_uri to send the user back to the Alexa app after authentication. For example, if the redirect_uri parameter is https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=M2AAAAAAAAAAAA, your login page would redirect the user to the following URL. You include the state and access_token parameters as a URL fragment starting with #.

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=vendor.id.1#state=xyz&access_token=sometoken.1&token_type=Bearer

Access tokens

You configure the access token endpoint for your authorization server in the Alexa developer console on the Build > Account Linking page by entering the appropriate URL in the Access Token URI field. After a user links their account, the Alexa service sends a POST request to the token URI containing the client credentials. Your authorization server should then generate and return an access token that uniquely identifies the user. This token should be specific to your resource server and created with security in mind. The token should identify the user but remain unguessable. For access token requirements, see Access token URI requirements. The following code shows an example access token request from Alexa.

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type=implicit
&client_id=exampleId
&redirect_uri=https://pitangui.amazon.com/api/skill/link/M3PCA6K3O9X0NW

On successful generation of the access token, the authorization server might send the following example response.

HTTP/1.1 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma: no-cache
{
   "access_token":"Atza|EXAMPLEACCESSTOKEN123456...",
   "token_type":"bearer",
   "expires_in":3600
}

Prerequisites

Make sure that you have an authorization server that meets the requirements described in Requirements for Account Linking.

Steps to configure an implicit grant

Configure your skill for the implicit grant type in the Alexa developer portal. For details, see Configure Account Linking in the Alexa Developer Portal.
Add logic to validate and use the access token to your skill code.
Test the account linking flow.

Step 1: Configure account linking

You can turn on account linking in the Alexa developer console on the Build > Account Linking page. Or, you can configure account linking with the ASK CLI or the Account Linking REST API.

Account linking settings

Under Settings, you enable and disable the account linking options available to your skill. The service provider options in the next section are based on the settings that you enable here. The following table describes the settings fields to configure account linking.

Field	Description
Do you allow users to create an account or link to an existing account with you?	Turn on to enable account linking for a custom skill. This option is automatically selected for smart home and video skills.
Allow users to enable the skill without account linking (Recommended)	Turn on to let users bypass the account linking flow when they enable your skill. Available for custom skills only. This option is useful if your skill offers meaningful functionality without an account, in addition to the features that require an account. For more details, see Let Users Enable Your Skill without Account Linking.This option is on by default.
Allow users to link their account to your skill from within your application or website	Turn on to allow users to authenticate by using your website.
Allow users to authenticate using your mobile application	Turn on to enable app-to-app account linking and allow users to authenticate by using your mobile app.
Allow users to link their account to your skill using voice	Turn on to enable customers to use their voice to link their Amazon account with the account they have with your service.

Security provider information

Under Security provider information, select the authorization grant type, and then configure the service provider information as shown in the following table. The options displayed here are based on the settings that you enabled in the settings section. If you use a third-party OAuth provider, see the documentation for that provider to determine the values to enter in these fields.

Step 2: Use access tokens in your skill

After you configure the implicit grant, add the logic to validate and use the access token in your skill code. Your skill can use the access token to retrieve user information from your resource server. For more details, see

Validate and Use Access Tokens in Custom Skill Code

Step 3: Test the account linking flow

After you configure account linking, you can test the account linking flow. Use the Alexa app to enable your skill and start the account linking process. Verify that you can log in to the service and then return to the Alexa app. To finish implementing account linking, update your skill code to check for the access token on incoming requests and take appropriate actions. Also, add code to send a link-account card in the response if the user didn’t enable or canceled account linking. When displayed in the Alexa app, this card displays a link to your authorization URI. The user can start the account linking process directly from this card.

Get Started

Plan and Implement

Reference

Implicit grant flow overview

Link the account

Use the access token in your skill

Authorization URI details

Alexa redirect URLs details

Access tokens

Prerequisites

Steps to configure an implicit grant

Step 1: Configure account linking

Account linking settings

Security provider information

Step 2: Use access tokens in your skill

Step 3: Test the account linking flow

​Implicit grant flow overview

​Link the account

​Use the access token in your skill

​Authorization URI details

​Alexa redirect URLs details

​Access tokens

​Prerequisites

​Steps to configure an implicit grant

​Step 1: Configure account linking

​Account linking settings

​Security provider information

​Step 2: Use access tokens in your skill

​Step 3: Test the account linking flow

​Related topics

Implicit grant flow overview

Link the account

Use the access token in your skill

Authorization URI details

Alexa redirect URLs details

Access tokens

Prerequisites

Steps to configure an implicit grant

Step 1: Configure account linking

Account linking settings

Security provider information

Step 2: Use access tokens in your skill

Step 3: Test the account linking flow

Related topics