Configure Authorization Code Grant

The Alexa Skills Kit supports authorization code grants for account linking in custom, smart home, video, and music skills.

In this grant type, the authorization server provides an authorization code (code) after the user authenticates with the service. Alexa then uses this code to request an access token / refresh token pair from the authorization server. Alexa can then use the refresh token to request a new access token after the old access token expires.

Overview of the Authorization Code Grant Flow

  1. The user starts the account linking process. The starting point depends on the type of skill:
  2. The Alexa app displays a login page within the app, using an 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.

  3. The user logs in using their credentials for the authorization server.
  4. Once the user is authenticated, the authorization server generates an authorization code (code).
  5. The authorization server redirects the user to the Amazon-provided redirect_uri and passes along the state and code in the URL query string parameters.
  6. The Alexa service uses the code to request an access token / refresh token pair from the authorization server's access token URI .

    Note that the authorization server must respond to the token request within 4.5 seconds.

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

  8. 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 (access_token). Your skill uses this token to get the information you need from the resource server. If the access_token is expired, Alexa calls the access token URI again with the refresh token to request a new access token / refresh token pair.

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

Authorization code grant flow
Authorization code grant flow

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.

Skill interaction sequence
Skill interaction sequence

Steps to Configure Authorization Code Grant

  1. Make sure you have an authorization server that meets the requirements for account linking with authorization code grant:

    • The authorization server must be able to accept the required parameters, authenticate the user, generate an authorization code, then redirect the user to the Amazon-provided redirect_uri.
    • The access token URI must accept client credentials and the authorization code and return an access_token (and optionally, a refresh_token that can be used to get a new access_token in the future) for the user.

    See Authorization URI for details.

  2. Configure your skill for authorization code grant in the developer portal. See Configure Account Linking in the Developer Console for details.

Once you have configured authorization code grant, move on to the next step and add the the logic to validate and use the access token to your skill code. See:

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 a code, which Alexa then exchanges for 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. You provide the URI of the server that can exchange the code for the access token in the Access Token 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 and access token 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 code for authorization code grant.

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 Car Fu 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 authorization URI must pass this value back (unchanged) when calling the redirect URL.

For example, if the authorization URI for your page is https://www.carfu.com/login, the URL called by the Alexa app might look like this:

https://www.carfu.com/login?state=abc&client_id=unique-id&scope=order_car%20basic_profile&response_type=code&redirect_uri=https%3A//pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA

Provide the Login Page in the User's Language

The Alexa app attempts to use the user's browser language preference to display a localized version of the app if the user's browser is set to one of the supported langauges . For other languages, the app defaults to en-us.

For a consistent user experience, your login page should also render in the same language as the Alexa app. To get the language, check the Accept-Language header first. The Alexa app attempts to set this when calling your authorization URI.

If the header is not set, you can use the language defined by the user's browser by checking navigator.language or navigator.browserLanguage. See Navigator language Property.

Note that the user's browser settings are independent of the language defined on the user's Alexa-enabled device. For example, a user could configure their device to use German, but configure their browser to use UK English. In this case, the Alexa app renders in English and the Accept-Language header is set to English (en-gb).

Provide a Good Login Experience for Your Users

The Alexa app displays the login page you specify when the user begins the account linking process. Be sure to provide a good user experience for users who are already using your service, and new users who discovered your service through Alexa and may want to create an account with your service.

Some best practices for your login page:

  • The username or email field on the login page should turn off the auto-correct and auto-capitalize options to reduce the likelihood of entry errors.
  • Use form-field validation to catch common errors such as trailing spaces and incorrect capitalization. For fields such as postal codes or phone numbers, make sure your validation logic is correct for each region your skill is accessible in.
  • The page should provide instructions about the user credentials it expects. For example, make it clear that the user must log in using credentials for your service, not their Amazon account. If you are using a third-party authentication server, make it clear that the user must log in with credentials for that server.
  • If the web site or mobile apps for your service support multiple sign-in mechanisms such as Facebook, Amazon, or Google, make sure your login page supports the same mechanisms. Otherwise some users who use your service will be unable to link their accounts.
  • If your web site or mobile apps for your service support creating new accounts, support and test this flow as well. Consider that a user might encounter your service for the first time through Alexa, so that user needs to be able to seamlessly create and link a new account.
  • Support account recovery options for users who have forgotten their account names or passwords.

Test the account linking flow with all of the above scenarios to ensure that your page gives users a good experience. Make sure that your error messages are clear about the problem when the user is unable to log in.

See also 10 Tips for Successfully Adding Account Linking to Your Alexa Skill.

Authorization URI Requirements

The authorization URI must meet the following requirements:

  • It must be served over HTTPS.
  • It must provide a mobile-friendly login page, as it will be displayed within the Alexa app.
  • This page cannot open any pop-up windows or launch any JavaScript alerts or message boxes. If the user encounters an error, (for example, the user enters the wrong username or email address and password), the error should be displayed inline on the same login page.
  • It must accept the user's credentials and then authenticate the user with the authorization server.
  • It must generate an authorization code that can be passed to your authorization server to retrieve an access token that uniquely identifies the user in the resource server .
  • It must keep track of the state value passed in the query string.
  • After authenticating the user, the page must redirect the user to an Amazon-provided redirection endpoint (redirect URL) .
    • The URL to use is included in the authorization request as the redirect_uri parameter.
    • Additional URLs are also displayed in the developer console when you configure account linking for your skill, so you can see the possible values your login page should expect in the redirect_uri parameter.
    • Include the state and code in the URL query string.

For example, assume your Amazon-provided redirect URL is the following:

https://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA

Your authorization URI would then redirect the user to:

https://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA?state=xyz&code=SplxlOBeZQQYbYS6WxSbIA

Note that the parameters are passed in the URL query string.

Access and Refresh 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 code and client credentials. The authorization server must return the access token and an optional refresh token.

Although the refresh token is optional, it is recommended if your access token expires. Note the following:

  • The authorization server must respond to the token request within 4.5 seconds.
  • The Alexa service can use the refresh token to get a new access token when the previous one expires, without disrupting the end user.
  • The authorization server should not immediately invalidate previously used access tokens when a new access token is given. This can cause outages in highly distributed and concurrent systems such as the Alexa service.
  • The authorization server should not invalidate or revoke access tokens that have been delivered to the Alexa service before the expires_in parameter of the access token response, unless the intent is to shut down access. There is no mechanism to notify the Alexa service that an access token that has been given is now invalid.
  • Access tokens must have a lifetime of at least 6 minutes. This means the expires_in parameter of your access token response must be greater or equal to 360.
  • The authorization server should not immediately invalidate previously used refresh tokens if a new refresh token is generated after each use. In addition to possibly causing outages in highly distributed and concurrent systems such as Alexa, this also tends to leave the user in a state from which the only recovery is to disable, enable, and account link the skill again from the Alexa App.

    The best practice is either to have refresh tokens that do not expire, or for refresh tokens that do expire, to keep X number of old refresh tokens valid, and only invalidate them if the authorization server has confirmed that the most recent refresh token was successfully received by Alexa and used to obtain a new access token.

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.

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 off by default.

Authorization Grant Type

The OAuth 2.0 authorization grant 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.

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.

Access Token URI

The URI for the access token endpoint for your authorization server.

The Alexa service calls this URI to exchange the authorization code for an access token . Alexa also calls this URI with the refresh token to get a new access token when the previous token expires.

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 https://api.amazon.com/auth/o2/token.

Refer back to Access and Refresh Tokens for token requirements and details.

Client ID

A unique string that identifies the client requesting authentication. This value is passed to the authorization URI in the client_id parameter.

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

Client Secret

A credential you provide that lets the Alexa service authenticate with the Access Token URI. This is combined with the 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.

Client Authentication Scheme

Identifies the type of authentication Alexa should use when requesting tokens from the Access Token URI.

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.carfu.com/login. If your page pulls in any content (such as images) from domains other than www.carfu.com, you need to add them to the Domain List. You can provide up to 30 domains.

Default Access Token Expiration Time

The time in seconds for which the access token is valid. This value is used if the OAuth client does not return expires_in. If the OAuth client returns expires_in, the value provided by the OAuth client is used instead.

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.

Redirection Endpoints (Redirect URLs)

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

Note Redirect URL 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.

Whitelist the Redirection Endpoints with the Authorization Server

You typically need to whitelist 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, whitelist all of the URIs shown in 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 authorization code grant might look like this:

https://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA

As noted in the authorization URI requirements, your authorization URI redirects the user to the redirect_uri and includes state and code in the URL query string. For example:

https://pitangui.amazon.com/api/skill/link/M2AAAAAAAAAAAA?state=xyz&code=SplxlOBeZQQYbYS6WxSbIA

Test the Account Linking Flow

Once you have configured 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:

Configure account linking in the CLI or Skill Management API:

OAuth Resources:

Other Resources: