Part 3 of Alexa Account Linking: How Alexa uses OAuth?

In part 3 of this series, we describe how an Alexa Skill can get an OAuth access token in the Skill Service. Having the OAuth access token is a prerequisite for calling an API later on.

So there are potentially a lot of new things to learn:

• Step (1) OAuth, see the OAuth Book
• Step (2) Getting an OAuth Access Token, see below
• Step (3) Alexa, see the Alexa Book
• Step (4) Alexa Account Linking, see Part 0: Introduction to Account Linking via OAuth
• Step (5) How OAuth is used withing Alexa Account Linking, see below

Step (2) of getting an OAuth access token is super technical. If you want to look me over the shoulder while doing this, check out this video on getting the Spotify OAuth token.

Step (5) dives into the details of Alexa OAuth with the account linking mechanism. If no OAuth access token is present, the Alexa Skill needs to log the Alexa end-user in on the OAuth authorization endpoint. This process is only available via GUI, so the Alexa Skill needs to direct the user to the screen of the device or of the Alexa App. The important part is the withLinkAccountCard() function, which calls the authorization URL specified in the Skill Interface configuration.

const Handler = {
handle(handlerInput) {
// get the access token from the context
var accessToken = handlerInput.
requestEnvelope.context.System.user.accessToken;
// no access token? need to trigger authorization
if (accessToken == undefined){
var speechText = "You need to link your Account."+
"Follow the instructions"+
"on the screen or in your Alexa App.";
return handlerInput.responseBuilder
.speak(speechText)
.withLinkAccountCard()
.getResponse();
}
}
};

When this handler returns, the user needs to sign in on the login page of the third-party (e.g. Spotify) in the Alexa companion App and consent to the data sharing. The technical complexity of the OAuth flow is hidden from the Skill developer, as the redirect endpoint is provided by Alexa and the token endpoint gets called automatically by Alexa with the correct parameters. As a result, we get the access token in the user object of the next request:

handlerInput.requestEnvelope.context.System.user.accessToken

Check out the other posts in this series on Alexa Account Linking:

• Part 0: Introduction to Account Linking via OAuth
• Part 1: Registration with OAuth Provider
• Part 2: Account Linking Configuration on Skill Interface
• Part 3: Skill Service: Get Access Token
• Part 4: Call Protected API from Skill Service

In my new book “Making Money with Alexa Skills – A Developer’s Guide” I describe not only how to develop, but also how to monetize Alexa Skills. Account linking is one of the possibilities for personalizing a Skill and make it unique – more practical approaches for personalizing Skills are described in the Alexa Book.

In the OAuth 2.0 book you can find a simple and understandable explanation of all the standard OAuth Flows (such as those supported by Alexa). What makes this book unique is that the complicated OAuth interactions are visualized as easy-to-understand Sequence Diagrams.

---

Also published on Medium.