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.

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.
|
You specify this URI by using:
|
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 You can also find the Alexa redirect URI in the developer console (Alexa Redirect URLs), ASK CLI, or SMAPI ( 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.
|
You specify this using:
|
Related topics
- Quick Reference: Add Account Linking to an Alexa Skill
- Add Account Linking to Your Alexa Skill
- The OAuth 2.0 Authorization Framework (RFC 6749)
- OAuth.com
Last updated: May 06, 2025