Configure an Authorization Code Grant
The Alexa Skills Kit supports authorization code grants for account linking in custom, smart home, video, meetings, and music skills.
For this grant type, the authorization server provides an authorization code after the user authenticates with the service. Alexa then uses this code
to request an access token and refresh token pair from the authorization server. Alexa uses the refresh token to request a new access token after the old access token expires.
Authorization code grant flow overview
Alexa uses the OAuth 2.0 account linking flow with authorization code 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.
Link the accounts
The following steps describe authorization code grant flow to link the user accounts.
- The user starts the account linking process by enabling a skill in the Alexa app. The starting point depends on the type of skill:
- For custom skills, see Account Linking for Custom Skills.
- For smart home, video, meetings, or music skills, see Account Linking for Smart Home and Other Domains.
- The Alexa app requests the authorization URL from the Alexa service.
- The Alexa service makes a request to the authorization URI that you provide when you configure account linking and includes
state
,client_id
,response_type
,scope
, andredirect_uri
as query string parameters. - The authorization server returns the authentication URL.
- The Alexa app displays the login page that lets the user authenticate with your authorization server.
For Website URLs, Alexa opens the login page in the in-app browser.
For app-to-app account linking, Alexa deep links to your app. - The user logs in with their credentials for the authorization server.
- After the authorization server authenticates the user, the server generates an authorization code (
code
). - The authorization server redirects the user to the
redirect_uri
included in Step 4. and includesstate
andcode
in the URL query string parameters. - The Alexa service sends the
code
andcode_verifier
in a POST request to get an access token and refresh token pair from the configured access token URI on your authorization server.Important: The authorization server must respond to the token request within 4.5 seconds - The server validates the authentication code, and then issues access and refresh tokens.
- Alexa saves the access token and refresh token.
The user's Alexa account is now linked to the account in the other 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–11.

Use the access token in your skill
When the user makes requests to the skill, each request, such as an IntentRequest
for a custom skill or a TurnOn
directive for a smart home skill, now includes the access_token
. Your skill uses this token to get the information you need from the resource server. If the access token expires, Alexa calls the access token URI again with the refresh token to request a new access token and refresh token pair.
This following diagram shows the skill interaction to use the access token to retrieve information from your resource server.

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 fields.
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=code&redirect_uri=https%3A//pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA
The Alexa service includes the following parameters in the query string when it opens your authorization URI.
Parameter | Description |
---|---|
|
An identifier for your skill. You can use this value to provide any skill-specific functionality, such as distinguishing between different skills you have configured with account linking. You define the |
|
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 Alexa developer console when you configure account linking for your skill. |
|
Indicates the type of response to return after the user was authenticated by the authorization server. The |
|
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.
|
|
A value used internally by the Alexa service to track the user through the account linking process. The Alexa service sends a |
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/api/skill/link/M2AAAAAAAAAAAA
, your login page would redirect the user to the following URL. You pass the state
and code
parameters in the query string.
https://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA?state=xyz&code=SplxlOBeZQQYbYS6WxSbIA
You typically register the redirection endpoint with the authorization server to so that the authorization URI can call the endpoint, especially if you don't own your authorization server. To verify that your skill works from multiple regions, register all the URIs shown in Your Redirect URLs.
How you do this depends on the authorization server you use. For example, in Login with Amazon, you configure a security profile and provide the possible redirect URLs in the Allowed Return URLs field.
To determine the requirements for your server, see the documentation for your OAuth provider.
Access and refresh token details
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 authorization code and 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. Although the refresh token is optional, if your access tokens expire, Amazon recommends that the server return a refresh token to allow for continued access without requiring the user to re-authenticate.
For access and refresh 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=authorization_code
&code=123456EXAMPLE
&client_id=exampleId
&client_secret=ABCDEFGEXAMPLE
&code_verifier=AB12CVEXAMPLE
&redirect_uri=https%3A//pitangui.amazon.com/api/skill/link/M3PCA6K3O9X0NW
On successful generation of the access and refresh tokens, 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,
"refresh_token":"Atzr|EXAMPLEREFRESHTOKEN123456X..."
}
Prerequisites
Make sure that you have an authorization server that meets the requirements described in Requirements for Account Linking for Alexa Skills.
Steps to configure an authorization code grant
Complete the following steps to configure your skill with account linking.
- Configure your skill for the authorization code 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 link their account to your skill using voice |
Turn on to enable customers to user 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.
Field | Description |
---|---|
Authorization Grant Type |
The OAuth 2.0 authorization grant type to use to obtain the access token. Select Auth Code Grant. For smart home and video skills, this is automatically selected, as this is the only supported grant type. |
Your Web Authorization URI |
The URI to open the authorization page on your web page for the user to log into your service. The Alexa app displays this page when the user begins the account linking process. For more details, see Authorization URI. For a third-party OAuth provider, look for the URI provided for authorization requests. For example, for Login with Amazon (LWA), the authorization URI is |
Your iOS App Authorization URI |
The Universal Link to open the authorization page in your iOS mobile app that for the user to log into your service. The Alexa app opens the app when the user begins the account linking process from an iOS mobile app. For more details, see Authorization URI. |
Your Android App Authorization URI |
The App Link to open the authorization page in your Android mobile app that for the user to log into your service. The Alexa app opens the app when the user begins the account linking process from an Android mobile app. For more details, see Authorization URI. |
Access Token URI |
The URI for the access token endpoint on your authorization server. The Alexa service calls this URI to exchange the authorization code for an access token. When the access token expires, Alexa also calls this URI to exchange the refresh token for a new access token. For a third-party OAuth provider, look for the URI provided for access token requests. For example, for Login with Amazon, the URI for the access token request is For more details about token requirements and details, see Access and Refresh Tokens. |
Your Client ID |
A unique string that identifies the client requesting authentication. This value is passed to the authorization URI in the This client ID is also part of the client credentials that the Alexa service includes when requesting an access token from the Access Token URI. 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. |
Your Secret |
A credential you provide that lets the Alexa service authenticate with the Access Token URI. This value is combined with Your Client ID to identify the request as coming from Alexa. For a third-party OAuth provider, look for the client identifier that the provider expects. For example, for Login with Amazon, the client secret is created when you create a security profile for Login with Amazon. |
Your Authentication Scheme |
Identifies the type of authentication Alexa should use when requesting tokens from the Access Token URI. |
Your Redirect URLs |
These URLs point to your own app and are only for app-to-app account linking implementations. |
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. Alexa includes all of the scopes entered here in the For a third-party OAuth provider, specify a scope from the set of scopes that the provider supports. For example, Login with Amazon supports |
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 field is only necessary for domains beyond your authorization URI. For example, suppose your authorization URI is |
Default Access Token Expiration Time |
The time in seconds for which the access token is valid. The Alexa service uses this value when the OAuth client doesn't return |
Alexa Client ID |
Credentials for your Alexa skill. |
Alexa Client Secret |
Credentials for your Alexa skill. |
Alexa Redirect URLs |
The Amazon-provided redirection endpoints to which your login page must redirect the user after the user authenticates with your service. Alexa passes the value to use for a given request to your login page as the |
Step 2: Use access tokens in your skill
After you configure the authorization code 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 the following resources based on your skill type:
- Validate and Use Access Tokens in Custom Skill Code
- Validate and Use Access Tokens in Smart Home and Video 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.
For more 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
Related topics
- Account Linking Concepts for Alexa Skills
- Quick Reference: Add Account Linking to an Alexa Skill
- The OAuth 2.0 Authorization Framework (RFC 6749)
- OAuth.com
Last updated: May 06, 2025