Account Linking Concepts

Account linking connects the user's Amazon identity with their identity in your system, enabling integration between Alexa and your service. To create this link, Alexa uses the OAuth 2.0 authentication framework. OAuth 2.0 enables your service to allow Alexa, with the user's permission, to access information from their account on your system, without sharing passwords.

Review the following OAuth concepts that you might encounter as you implement account linking. These concepts describe the principles of the recommended account-linking implementation for Alexa.

Account linking overview

To access the user's account in your system, Alexa skills need access tokens. Account linking is the process of getting user permission to obtain these access tokens. After the user grants this permission, Alexa includes the token in requests to your skill. The skill uses the token in API calls to your server to access the user's data.

In the authorization code grant type, the Alexa service follows a two-step process. First, it obtains an authorization code from your authorization server. Then, Alexa exchanges this code for an access token and a refresh token. The refresh token allows Alexa to request a new access token when the original access token expires.

The following figure shows the relationship between the key components of account linking, described later in this topic. The figure assumes that you own the server that contains the user data, though you might use a third party server. For examples from a user's perspective, see How Users Experience Account Linking.

Account linking using authorization code grant. — Click to enlarge

Account linking methods

Alexa supports multiple methods for account linking, including standard account linking, app-to-app account linking, and account linking with Login with Amazon (LWA). For a description of each method, see Add Account Linking for Alexa.

OAuth roles

OAuth 2.0 defines four roles: resource owner, resource server, client, and authorization server. Review these roles in the context of the Alexa service.

Resource owner

The resource owner is the Alexa user who wants to connect your skill and link it to their account in your system. For example, a user who wants to connect the Ride Hailer custom skill to their Ride Hailer account or a user who wants to enable your smart home skill and link it to their My Lights account so that they can control their My Lights devices with Alexa.

Resource server

The resource server hosts the protected resource (user data) that your skill needs to access, with the user's permission. For example, the resource server might be a database containing user profiles with payment information, or a cloud-based service that controls smart devices in a user's home.

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

For example, to order the user a ride, the Ride Hailer skill communicates with the resource server to retrieve the user's Ride Hailer account profile with their payment information. To turn on the lights, the My Lights smart home skill communicates with the resource server to retrieve information about the user's lights.

Authorization server

The authorization server identifies and authenticates the identity of the Alexa user with a user in your system. The server is essential in account linking because it performs the following functions.

Displays a log-in page for the user to sign in to your system.
Authenticates the user in your system.
Generates an authorization code that identifies the user.
Passes the authorization code to the Alexa service.
Accepts the authorization code from the Alexa service and returns an access token to the Alexa service for accessing the user's data in your system.

Because it handles token exchanges, the authorization server is sometimes called a token server.

You can use a third-party authorization server, such as Login with Amazon, or build your own. Either way, 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, you can use the Amazon profile:user_id to look up a user's profile in your database.

Codes and tokens

Account linking uses an access token to access protected resources, such as the user's account with your service. In the authorization code grant type, the client must first get an authorization code and then exchange that for an access token and refresh token.

Authorization code

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 server provides 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 secure, time-limited credential issued by your token server after the Alexa service exchanges the authorization code obtained during user authentication. The access and refresh token pair uniquely identifies the user in your system and represents the user's permission for the Alexa skill to access their protected resources. Your token server controls what data the token grants access to and when the token expires. After the Alexa service obtains the access token from your token server, Alexa includes the access token in requests sent to your skill.

Refresh token

A refresh token is a credential that the Alexa service uses to request a new access token after the previous access token expires. This process happens automatically without disrupting the user.

Reciprocal access token

Reciprocal access tokens are used in reciprocal authorization, which allows a pair of resources, such as the Amazon account used with Alexa and the account with your service, to be synced and updated between the two accounts. Reciprocal authorization is available for Alexa skills only.

PKCE code challenge

For the authorization code grant type, the Alexa service implements Proof Key for Code Exchange (PKCE) security measures to prevent authorization code interception attacks. This process verifies that the token request comes from the same client that initiated the authorization request.

As defined in RFC 7636, the client creates a secret key (code_verifier), encodes it into a secure format (code_challenge) using SHA-256, and then sends the code_challenge in the authorization request to the authorization server. Later, when requesting an access token, the client proves its identity by sending the original code_verifier with the token request. The server verifies the keys before issuing the access token.

Note: Account linking supports the SHA-256 code challenge method only.

Grant types

OAuth 2.0 defines grant types. Grants are ways for a user to authorize access to their user data in another system. Alexa supports two grant types: the authorization code grant, the most common, and the implicit grant with limited uses. Amazon recommends the authorization code grant type for security and usability reasons. The Alexa account linking documentation focuses on the authorization code type.

Authorization code grant type

In the authorization code grant type, 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.

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 uses the refresh token to request a new access token.

Implicit grant type

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 provide the ability to authenticate and authorize users in your system. However, some services 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. Reciprocal authorization is available for Alexa skills only

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
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 query parameters that include the client ID, redirect URI, response type, state, and scope. You specify this URI when you configure account linking for your skill. For a list of requirements for the authorization server, see Authorization URI requirements.
Alexa redirect URI	Your authorization server calls this URI to redirect 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 must register the Alexa redirect URI with your authorization server. 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 receives an authorization code and returns an access and refresh token pair. The Alexa service makes a `POST` request to the access token URI and includes the authorization code in the parameters. The token server responds with the access and refresh tokens in JSON. You specify this URI when you configure account linking for your skill.

Was this page helpful?

Provide feedback

Last updated: Jul 14, 2026