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 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 are not described here.
- URIs that account linking uses
- Related topics
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.
This section reviews concepts that you might encounter as you implement account linking.
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).
This is the Alexa user who wants to enable your skill and link it to their account in your system.
- In the Ride Hailer example, the resource owner is the user who wants to enable the Ride Hailer skill and link it to their Ride Hailer account so that they can request rides.
- In the My Lights example, the resource owner is the user who wants to enable your skill and link it to their My Lights account so that they can control their My Lights devices with Alexa.
This is the server that hosts the protected resource (user data) that the Alexa skill needs to access, with the user's permission.
- In the Ride Hailer example, the resource server might be a database containing profiles for Ride Hailer users. The protected resource is the user's Ride Hailer account profile with their payment information, stored in this database.
- In the My Lights example, the resource server is the cloud-based My Lights service that can control light switches in a user's home. The protected resource is the user's My Lights account, with information about the user's smart devices that the service controls.
This is the Alexa skill that is 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 is the only component that ever accesses the protected resource (user data) in the resource server.
- In the Ride Hailer example, the Ride Hailer skill communicates with the resource server to retrieve the user's Ride Hailer account profile with their payment information, so that the skill can order the user a ride.
- In the My Lights example, the My Lights skill communicates with the resource server to retrieve information about the user's lights so that it can turn a light on or off.
This is the server that 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 Oath2.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
As described previously, account linking for Alexa skills involves using an access token to access the resource (in this case, the user's account with your service). In the most typical scenario (authorization code grant type), 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. These are described next.
This is a code that your authorization server gives the Alexa service so that the Alexa service can exchange the code for an access/refresh token pair. 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.
This is a credential that your token server gives the Alexa service in exchange for the authorization code that your authorization server gave the Alexa service after the user logged into your authorization server. The access/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 if the user has successfully linked their account.
For access token URI requirements, see Access token URI requirements.
This 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 (the Amazon account they use with Alexa, and the account with your service) to be synced and updated between the two accounts.
OAuth 2.0 defines a number of grant types. Grants are ways for a client application (in this case, an Alexa skill) to authorize the user and obtain an access token that it can use to authenticate a request to the resource server. There are two grant types that 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 because it is the recommended grant type for security and usability reasons.
Authorization code grant type
This is 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. (This was described in Codes and tokens also.) 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/refresh token pair from your token server, using the access token endpoint (URI). The refresh token can then be used to request a new access token after the old token expires. Implement the authorization code grant type unless you are sure that you want the implicit grant type.
Implicit grant type
This is a grant type for requesting the end user's authorization to access their information in another system. In an implicit grant, the authorization server returns the access token once the user logs in. This grant type is less secure, and is limited compared to the authorization code grant type. Only custom skills can use the implicit grant type.
Reciprocal authorization is when the user allows a pair of resources to be synced and updated. Typical account linking allows Alexa 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, this is achieved by a reciprocal authorization endpoint, which you host to obtain an authorization code from Alexa.
URIs that account linking uses
This section describes the URIs that relate to account linking.
|Name||Description||Where you specify or get it|
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 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 whitelist 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/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/refresh tokens in JSON.
You specify this using: