Setting up Alexa Account Linking with Amazon Cognito

alexa account linking

Alexa Skills are increasingly trying to provide more personalized user experience by offering information about your children's school hours, your electricity bill, etc. In order to achieve this, it is necessary to identify yourself in the Skill with a user and password through an external platform. To do so, Alexa offers Account Linking, which allows us to identify ourselves on our platform with Alexa using the OAuth2 authentication protocol. 

This authentication flow is simple on the user´s side, but can be complex for the developer. This is why we have thought it would be interesting to explain how to set up, following some simple steps, an authentication server and configure the Account Linking to be able to login in our platform when activating the Skill.


To exemplify and create the authentication server, we will use Amazon Cognito as it is an easy to set up service that everyone can try as we will not exceed the limits of its free offering

Account Linking_AWS

Step by Step

First we access the Cognito service and select the Manage User Pools option: 

Amazon Cognito

Then, we select "Create a User Pool" option and we will get a screen like this: 

Amazon Cognito_userpool

Notice that we will not go into detail about the configuration of the authentication service as each developer will have a different need. Here is a basic configuration.


Amazon Cognito_attributes

The Policies section is set by default. 

MFA and verifications, do not forget you need to create the role. 

Amazon Cognito_MFA

We left by default all remaining sections until we reach the App Clients option and select Add an App Client. 

Amazon Cognito_appclient

At this step it is important to select the "Generate Client Secret" option. When doing so, we add a name and create our first App Client. 


Now, before reviewing the configuration, we are ready to create our user pool.

Amazon Cognito_create user pool

Once the user pool is created, we will get a menu with new options:

Amazon Cognito_ menu

When selecting "App Integration" you will see it refers to the client created in the previous steps.

Amazon Cognito_ app integration

Next step is to assign a domain name:

Amazon Cognito_ dominio

Now, we'll make a parenthesis and go to our Alexa skill, specifically to the Account Linking section, and the first thing we'll do is to enable it. Depending on your Skill, you will have to activate or not the rest of the options.

Amazon Cognito_ account linking

And now, it is time to set the Account Linking. This step is really easy and what we have to do is to select the Auth Code Grant option where we will see the fields we must fill in with the information of our newly created authentication service. 

Amazon Cognito_ Auth Code Grant


Next, we go to our Amazon Cognito service and copy the url of the created domain:

Amazon Cognito_ domain

In this case, our url is: with which we can fill in the first two fields:

1. Authorization URI (Uniform Resource Identifier):

As you can see, we added the oauth2/authorize path and the following url parameters:

  • response_type=code
  • redirect_uri= (they appear at the bottom of the Account Linking view). 

In case you need more information about Account Linking parameters while setting up the account, we recommend to read this document by Amazon.

2. Access Token URI:

Client ID and Client Secret

To obtain these values we go back to our Amazon Cognito service, specifically to the App Client menu.

Amazon Cognito_ app client ID

We can leave the remaining parameters by default.

Once we are ready with this step we can try the authentication with Account Linking. With the Alexa account linked we will obtain the user's access token but we will not be able to access any of our API resources if it uses our user pool as authorizer

Amazon Cognito expects the token ID rather than the access_token so if we try to access our API with the access token we will obtain an "Unathorized". This happens because Amazon Cognito uses the OpenID authentication protocol while Alexa uses the OAuth2 authentication protocol. This can be easily fixed by going to the App Client settings menu.

The configuration must be similar to the one shown. Please, notice that we checked the Authorization Code Grant and OpenID scope.

Also we've added all the redirect urls (we can get them from the Alexa Account Linking menu) and the logout url, that we'll build in a similar way to the previous ones:

Amazon Cognito_ OAuth

We save the changes and we can now log in to our Skill. Now in each invocation of the skill we will have an Access Token. In the Access Token we won't have all of the user's information, we'll just have the username, unlike the token_id where we had all of the information. To get the user's information (in case we need it for our Skill) we can get it through a link like this

This call can be done by sending the Access Token to the header.

Example of javascript code:

Amazon Cognito_ javascript

And now we are ready to go! We have been able to list the main steps to configure the Alexa Account Linking authentication server through Amazon Cognito.

Following these instructions you will be ready to activate your Alexa Skill and log in.

On the next article, we will show you how to use your own front-end to log in instead of the one provided by Amazon Cognito. Stay tunned for our next Alexa blogpost!


We invite you to learn more about virtual voice assistants by reading our other blogpost:


Stay tunned for more content like this.

Nueva llamada a la acción
Linke SAP on AWS
Key steps to adopt Devops on a Cloud-Native Company
Download The Linke AWS Connector for SAP in PDF