Configure an Implicit Grant

Note: Sign in to the developer console to build or publish your skill.

The Alexa Skills Kit supports implicit grants for account linking in custom skills. You cannot use this grant type for other types of skills, such as smart home skills.

Important: In an implicit grant, your authorization server provides the access token directly after the user authenticates with the other service. This flow does not support access tokens that expire. If the access token expires, the user must re-link their account, which is a poor user experience. Therefore, implicit grant is not recommended for most skills. Implement authorization code grant if possible.

Overview of the implicit grant flow
Steps to configure an implicit grant
Authorization URI
- Parameters passed to the authorization URI
Access tokens
Configure account linking
- Alexa Redirect URLs
Test the account linking flow
Related topics

Overview of the implicit grant flow

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.

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.
When the user makes requests to the skill, every request sent to the skill (such as an IntentRequest) now includes the access token (access_token). Your skill uses this token to get the information you need from the resource server.

The following diagram illustrates the initial setup when the user links their account and Alexa obtains the access token from your authorization server.

This 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.

Steps to configure an implicit grant

Make sure that you have an authorization server that meets the requirements described in Requirements for Account Linking for Alexa Skills.
Configure your skill for the implicit grant type in the developer portal. For details, see Configure Account Linking in the Developer Console.

After you configure the implicit grant, move on to the next step and add the logic to validate and use the access token to your skill code. For more information, see:

Validate and Use Access Tokens in Custom Skill Code

Authorization URI

When a user starts the process of linking accounts, the Alexa app displays a login page for the authorization server. The authorization server needs to validate the user's credentials and then return an access token.

You specify the URL for this login page in the developer console on the Build > Account Linking page. You provide the URL for the login page in the Authorization URI field.

Authorization URI for Third-party OAuth Providers

If you use a third-party OAuth provider, see the documentation for that provider to determine the authorization URI you need when you configure account linking. Look for the URI for an authorization request.

Parameters passed to the authorization URI

The Alexa app includes the following parameters in the URL query string when it calls your authorization URI.

Parameter	Description
`client_id`	An identifier for your skill. You can use this to provide any skill-specific functionality, such as distinguishing between different skills you have configured with account linking. You define the `client_id` when you configure account linking for your skill.
`redirect_uri`	The Amazon-specific redirection endpoint (redirect URL) to which the service should redirect the user after authenticating the user. The values you can expect for this parameter are also displayed in the developer console when you configure account linking for your skill.
`response_type`	Indicates the type of response that should be returned after the user has been authenticated by the other service. This is always `token` for the implicit grant type.
`scope`	An optional list of scopes indicating the access the Alexa user needs. You define these scopes when you configure account linking for your skill for your skill. The service can use this information when generating the access token. For example, a service could create a token that allows access to basic profile information in the resource server, but does not allow access to payment information. Multiple scopes can be used. The list is delimited by URL-encoded spaces. The login page should tell users what access they are allowing by linking their accounts. For instance, your login page could display text such as "This allows the Ride Hailer skill to order a taxi on your behalf and charge your account for the cost." For a smart home skill, this page might display "This allows the My Lights skill to control lights connected to your My Lights hub."
`state`	A value used internally by the Alexa service to track the user through the account linking process. The Alexa app sends a `state` value to your authorization server via the authorization URI. Your authorization server must use that same `state` value when it subsequently calls the redirect URI for that particular account linking request. Each request to the authorization server has its own `state` value.

Access tokens

Your authorization server needs to provide an access token that uniquely identifies a user. Your skill can then use this token to access information about the user in your resource server.

The Alexa service calls the access token endpoint for your authorization server (specified as the Access Token URI in the developer console) and passes the client ID in a POST request. The authorization server returns the access token in a JSON response.

Note: Implicit grants don't return refresh tokens.

Example access token request:

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%3A//pitangui.amazon.com/api/skill/link/M3PCA6K3O9X0NW

Example access token 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
}

For access token requirements, see Access token URI requirements.

When generating the access token, provide a token specific to your resource server. For security, your token should be a value that identifies the user, but cannot be guessed.

Configure account linking

You enable account linking in the developer console in the Build > Account Linking section. Alternatively, you can configure account linking with the ASK CLI or the Skill Management API.

Note: Account linking is optional for custom skills. However, once a custom skill with account linking has been certified and published to users, you cannot disable account linking for that skill.

The following table summarizes the fields you must fill in to configure account linking. If you use a third-party OAuth provider, see the documentation for that provider to determine the values to enter in these fields.

Field	Description
Do you allow users to create an account or link to an existing account with you?	Select this 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	Select this to let users bypass the account linking flow when they enable your skill. Available for custom skills only. This is useful if your skill offers meaningful functionality without an account, in addition to the features that require an account. See Let Users Enable Your Skill without Account Linking. This option is on by default.
Authorization Grant Type	The OAuth 2.0 authorization grant type to use to obtain the access token. Select Implicit Grant.
Authorization URI	The URI for a page the user can use to log into your service. The Alexa app displays this page when the user begins the account linking process. Refer back to Authorization URI for details and requirements. For a third-party OAuth provider, look for the URI provided for authorization requests. For example, for Login with Amazon, the authorization URI is `https://www.amazon.com/ap/oa`.
Your Client ID	A unique string that identifies the client requesting authentication. This value is passed to the authorization URI in the `client_id` parameter. For a third-party OAuth provider, look for the client identifier that the provider expects. For example, for Login with Amazon, this ID is created when you create a security profile for Login with Amazon.
Scope	An optional list of permissions for the other service. If your resource server supports different scopes for access, enter those here. You can provide up to 15 scopes. All of the scopes entered here are included in the `scope` parameter (separated by URL-encoded spaces) when the Alexa app calls your authorization URI. For a third-party OAuth provider, specify a scope from the set of scopes that the provider supports. For example, Login with Amazon supports `profile`, `profile:user_id`, and `postal_code`.
Domain List	An optional list of domains that the authorization URI can retrieve data from. If your login page retrieves content from other domains, enter those in this list. This is only necessary for domains beyond your authorization URI. For example, suppose your authorization URI is `https://www.ridehailer.com/login`. If your page pulls in any content (such as images) from domains other than `www.ridehailer.com`, you need to add them to the Domain List. You can provide up to 30 domains.
Alexa Redirect URLs	This displays the Amazon-provided redirection endpoints to which your login page must redirect the user after the user is authenticated. The value to use for a given request is passed to your login page as the `redirect_uri` parameter included with the authorization URI. See Redirection Endpoints.

Alexa Redirect URLs

You can see the redirection endpoints that Alexa uses in the Alexa Redirect URLs field on the Build > Account Linking page in the developer console. This endpoint is the URL to which your log-in page must redirect the user after the user is authenticated.

Note that Alexa Redirect URLs displays multiple URIs. The Alexa app passes your authorization URI the value you should use based on where the user registered their device. The URI is passed to your authorization URI in the redirect_uri parameter.

Register the Redirection Endpoints with the Authorization Server

You typically need to register the redirection endpoint with the authorization server to ensure that the authorization URI can call it, especially if don't own your authorization server. To ensure that your skill works from multiple regions, register all of the URIs shown in Your Redirect URLs.

How you do this depends on the authorization server you are using. For example, in Login with Amazon, you need to configure a security profile and provide the possible redirect URLs in the Allowed Return URLs field.

See the documentation for your OAuth provider to determine these requirements.

For example, the value passed in the redirect_uri parameter for an implicit grant might look like this:

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=M2AAAAAAAAAAAA

As noted in the authorization URI requirements, your authorization URI redirects the user to the redirect_uri and includes state, access_token, and token_type in the URL fragment. For example:

https://pitangui.amazon.com/spa/skill/account-linking-status.html?vendorId=M2AAAAAAAAAAAA#state=xyz&access_token=2YotnFZFEjr1zCsicMWpAA&token_type=Bearer

Note: If you distribute your skill in multiple regions, your skill needs to use the correct region-specific Redirect URL. The URL to use is included in the call to your login page in the redirect_uri parameter.

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, you need to update your skill code to check for the access token on incoming requests and take appropriate actions. For details, see:

Custom skills: Validate and Use Access Tokens in Custom Skill Code
Smart home skills and other domains: Validate and Use Access Tokens in Smart Home and Video Skill Code

Last updated: Jul 21, 2022