Account Linking Concepts for Alexa Skills

To create a link between the Alexa user's Amazon account and the account that they have with your service, the Alexa Skills Kit (ASK) uses the OAuth 2.0 authentication framework. OAuth 2.0 defines a means by which your service can allow Alexa, with the user's permission, to access information from the account that the user has set up with you.

This topic describes OAuth 2.0 concepts in the context of the most common account-linking implementation for Alexa skills: Alexa-app only account linking with the authorization code grant type. Less common variants of account linking, such as a different grant type (implicit grant) or an alternate flow (app-to-app account linking) share many of the same concepts but aren't described here.

Account linking overview

For Alexa skills, account linking rests on the concept that to access the user's account in your system, the Alexa skill must use an access token. In other words, to "link accounts" means "to get the user's permission to obtain an access token" so that the skill can use the access token in API calls to the server that contains the user data. Here, we assume that you own the server that contains the user data, though it could be owned by a third party.

In the most typical scenario (authorization code grant type), the Alexa service does not get an access token directly: it must first get an authorization code and then exchange that for an access token (and, optionally, a refresh token so that it can request a new access token when the old access token expires). The following figure shows the relationship between the key components of account linking, which are described later in this topic. For an example of how users experience the account linking flow, see How Users Experience Account Linking for Alexa Skills.

Alexa app-to-app account linking.

Concepts

Review the following concepts that you might encounter as you implement account linking.

OAuth roles

OAuth 2.0 defines four roles: resource owner, resource server, client, and authorization server. The following sections describe these roles in the context of Alexa skills. The examples use a fictional custom skill that lets users order rides (Ride Hailer) and a smart home skill that can control lighting (My Lights).

Resource owner

The resource ownder is the Alexa user who wants to enable your skill and link it to their account in your system.

Resource server

The resource server hosts the protected resource (user data) that your skill needs to access, with the user's permission.

Client

The client is the Alexa skill making requests to your resource server on behalf of the Alexa user, with the user's permission.

Although the skill is the OAuth client, Alexa performs some operations on behalf of the skill. For example, Alexa makes requests to the authorization server to get an access token. The skill is still considered the client because it's the only component that ever accesses the protected resource (user data) in the resource server.

Authorization server

The authorization server identifies and authenticates the identity of the Alexa user with a user in your system. It plays a key role in account linking in that it: 1) displays a log-in page for the user to log into your system, 2) authenticates the user in your system, 3) generates an authorization code that identifies the user, and 4) passes the authorization code to the Alexa app, and finally, 5) accepts the authorization code from the Alexa service and returns an access token that the Alexa service can use to access the user's data in your system. Due to that last step, the authorization server is sometimes also called a token server.

You can use a third-party authorization server, such as Login with Amazon, or build your own. In any case, the authorization server must support OAuth 2.0. If you use a third-party authorization server, the authorization server provides you with data that you can map to your users in your resource server. For example, if you use Login with Amazon to authenticate users, and then use the Amazon profile:user_id to access a user's profile in your database.

For authorization URI requirements, see Authorization URI requirements.

Codes and tokens

Account linking for Alexa skills uses an access token to access the resource, such as the user's account with your service. In the authorization code grant type scenario, the client must first get an authorization code and then exchange that for an access token and, optionally, a refresh token so that it can request a new access token when the old access token expires.

Account linking supports the following codes and tokens:

Authorization code

For the authorization code grant type, your authorization server gives the Alexa service an authorization code so that the Alexa service can exchange the code for an access and refresh token pair. After the user logs into your authorization server, your authorization server gives the Alexa service the authorization code by including it in the query string when it redirects the user back to the Alexa app.

Access token

An access token is a credential vended by your token server when the Alexa service exchanges the authorization code provided during customer authentication. The access and refresh token pair identifies the user in your system and represents the user's permission for the Alexa skill to access their data in your system. After the Alexa service gets the access token from your token server, it includes the access token in requests sent to your skill when the user has successfully linked their account.

For access token URI requirements, see Access token URI requirements.

Refresh token

A refresh token is a credential that the Alexa service can use to request a new access token after the old access token expires.

Reciprocal access token

Reciprocal access tokens are used in reciprocal authorization, which is a way for the user to allow a pair of resources, such as the Amazon account they use with Alexa, and the account with your service, to be synced and updated between the two accounts.

Grant types

OAuth 2.0 defines a number of grant types. Grants are ways for a client application (here, an Alexa skill) to authorize the user and obtain an access token that it can use to authenticate a request to the resource server. Two grant types apply to Alexa skills: the authorization code grant (the vast majority of cases) and the implicit grant (limited use). The Alexa account linking documentation focuses on the authorization code grant type as the recommended grant type for security and usability reasons.

Authorization code grant type

The grant type in which the Alexa service gets an authorization code from your authorization server, exchanges it for an access token, and then passes the access token in requests to your skill as described in Codes and tokens. In an authorization code grant, your authorization server gives the Alexa service the authorization code by including it in the query string when it redirects the user back to the Alexa app after the user logs into your authorization server. The Alexa service then uses this code to request an access and refresh token pair from your token server, using the access token endpoint (URI). After the access token expires, the Alexa service users the refresh token to request a new access token. Implement the authorization code grant type unless you're sure that you want the implicit grant type.

Implicit grant type

The grant type for requesting the user's authorization to access their information in another system. In an implicit grant, the authorization server returns the access token after the user logs in successfully. This grant type is less secure than the authorization code grant type. Only custom skills can use the implicit grant type.

Reciprocal authorization

Reciprocal authorization is when the user allows a pair of resources to be synced and updated. Typical account linking allows Alexa skills to access resources in your system. Reciprocal authorization goes a step further, in that it allows you to access Alexa resources as well.

Most OAuth servers only provide the ability to authenticate and authorize users in your system. However, some skills must proactively interact with the Alexa backend to make updates. In Alexa, reciprocal authorization is achieved by a reciprocal authorization endpoint, which you host to obtain an authorization code from Alexa.

URIs for account linking

Account linking uses the following URIs. Alexa passes parameters to the authorization server as part of the URI query string.

Name Description Where you specify or get it

Authorization URI

The URI of your authorization server, which provides the Alexa service with an authorization code. The Alexa service calls the authorization URI with these query parameters.

For a list of requirements for the authorization server, see Authorization URI requirements.

You specify this URI by using:

  • Developer console (Authorization URI)
  • ASK CLI (Authorization URL)
  • SMAPI (authorizationUrl).

Alexa redirect URI

Your authorization server calls this URI to take the user back to the Alexa app after they log into your system.

Use the value that the Alexa service passes as the redirect_uri query parameter when it calls your authorization URI.

You can also find the Alexa redirect URI in the developer console (Alexa Redirect URLs), ASK CLI, or SMAPI (redirectUrls). However, these sources list multiple redirect URIs because the final value depends on where the user registered their Alexa device. Instead, use the redirect_uri that Alexa passes to your authorization URI as a query parameter.

You must register the Alexa redirect URI as described in Authorization URI requirements.

Access token URI

The URI of your token server, which is the endpoint of your authorization server that can receive an authorization code and return an access and refresh token pair that the Alexa service can use to access the user's data in your system. The Alexa service makes a POST request to the access token URI and includes the authorization code in the parameters. The token server responds and includes the access and refresh tokens in JSON.

For a list of requirements, see Access token URI requirements.

You specify this using:

  • Developer console (Access Token URI)
  • ASK CLI (Access Token URI)
  • SMAPI (accessTokenUrl).
Was this page helpful?

Last updated: May 06, 2025

DevAssistant