How can users grant permission for my website to manage their Amazon Alexa Lists

Question

I want users of my Next.js TypeScript app to grant it permission to manage their Alexa Lists.

I figured this would be possible with OAuth2.

I figured I'd need to create a button in my website that takes the user to an Amazon URL that allows the user to grant my website permission to manage their Alexa lists (and then generates a code that it includes in a GET request that happens as a redirect to a "callback" URL that I registered as the redirect_uri when setting up OAuth2 in Amazon).

I figured the button would be a link to a URL defined like

const url = `${oauth2BaseUrl}?client_id=${encodeURIComponent(clientId)}&redirect_uri=${encodeURIComponent(redirectUrl)}&response_type=code&scope=${scope}`;

This is generally how OAuth2 works, in my experience.

But I've found Amazon's docs incredibly unhelpful.

I see permissions / scopes mentioned here called alexa::household:lists:read alexa::household:lists:write.

I've set up my API endpoint (which I'll specify at redirectUrl) to exchange the Amazon authorization code for an Amazon access token following the code examples shown there.

I've set oauth2BaseUrl to be 'https://www.amazon.com/ap/oa' (found at https://developer.amazon.com/docs/login-with-amazon/authorization-code-grant.html).

For client ID, I'm using the one for my Alexa skill that I created. Is that correct?

I'm using Next-auth, but I'd be curious if there are any other libraries that could make any of this easier.

Here are permissions I've added in my Skill:

I always get:

400 Bad Request
An unknown scope was requested

But if I just use scopes these different scopes instead, I see it behave how I'd expect (but I lack List permissions): alexa::skills:account_linking postal_code profile:user_id.

P.S. I also started setting up Login With Amazon, but I don't understand why that would be necessary. I'm not looking to offer a federated login feature.

Answer 1

I got your ping from another thread. I haven't used App-to-App account linking, so I don't have a complete answer for you. But to my knowledge, alexa::household:lists:read and alexa::household:lists:write are skill permissions (not OAuth scope). If enabled, the Alexa app would prompt for the user's consent after the OAuth authentication flow.

For example, here is the basic account linking flow (not App-to-App account linking) with the Alexa app on Android:

1. Open the Alexa app
2. Select my skill > Enable
3. The Alexa app opens Login with Amazon page in Chrome (I used LWA as my OAuth provider)
4. I login and authorize the request
5. It returns to the Alexa app, with the message "Your skill account has been successfully linked" > click Close
6. The Alexa app then prompts for Account Permissions. That's the step where I can grant the skill access to my Alexa lists

So granting the Alexa lists permission is not part of the OAuth in the basic account linking flow.

As an experiment, I tried adding alexa::household:lists:read as a scope in my skill's account linking configuration, and it broke account linking -- Alexa app would display an error message instead of opening the LWA page. So I don't think they are OAuth scopes. It would also explain why you were getting 400 Bad Request -- An unknown scope was requested error.

As for your scenario, are you looking to implement App-to-App account linking with the Alexa app flow or the LWA fallback flow? If it's the latter, I suspect this may not be a supported use case based on my observation above. I would suggest reaching out to Amazon developer support to confirm.

Answer 2

1. Go to the Amazon Developer Console.
2. Click on "Login with Amazon" in the top-right menu.
3. Click on "Create a New Security Profile".
4. Fill in the required information and click on "Save". In the "Web Settings" tab of your new security profile, add your redirectUrl to the "Allowed Return URLs".
5. Note the "Client ID" and "Client Secret" provided in the "General" tab. Use this new Client ID in your OAuth2 request.

And update your OAuth2 request URL to include the correct client ID and requested scopes for Alexa Lists

const oauth2BaseUrl = 'https://www.amazon.com/ap/oa';
const clientId = 'YOUR_LOGIN_WITH_AMAZON_CLIENT_ID';
const redirectUrl = 'YOUR_REDIRECT_URL';
const scope = 'alexa::household:lists:read alexa::household:lists:write';

const url = `${oauth2BaseUrl}?client_id=${encodeURIComponent(clientId)}&redirect_uri=${encodeURIComponent(redirectUrl)}&response_type=code&scope=${encodeURIComponent(scope)}`;

Next-auth does not directly support Alexa Lists API. Next-auth is an authentication library for Next.js, which simplifies adding authentication to your app. While it supports Login with Amazon, it does not provide built-in support for the Alexa Lists API.

You can use the amazon provider in Next-auth for Login with Amazon, but you would still need to handle Alexa Lists API calls yourself.

For the APP:

Create a component in your Next.js app to generate the OAuth URL and render the button:

// components/LinkWithAmazon.tsx

import React from 'react';

const oauth2BaseUrl = 'https://www.amazon.com/ap/oa';
const clientId = process.env.CLIENT_ID;
const redirectUrl = process.env.REDIRECT_URL;
const scope = 'alexa::household:lists:read alexa::household:lists:write';

const url = `${oauth2BaseUrl}?client_id=${encodeURIComponent(clientId)}&redirect_uri=${encodeURIComponent(redirectUrl)}&response_type=code&scope=${encodeURIComponent(scope)}`;

const LinkWithAmazon: React.FC = () => (
  <a href={url}>Link with Amazon Alexa</a>
);

export default LinkWithAmazon;

Implement a Next.js API route to handle the callback from Amazon and exchange the authorization code for an access token:

// pages/api/auth/callback.ts

import type { NextApiRequest, NextApiResponse } from 'next';
import axios from 'axios';

async function handler(req: NextApiRequest, res: NextApiResponse) {
  const { code } = req.query;

  const response = await axios.post('https://api.amazon.com/auth/o2/token', null, {
    params: {
      grant_type: 'authorization_code',
      code,
      client_id: process.env.CLIENT_ID,
      client_secret: process.env.CLIENT_SECRET,
      redirect_uri: process.env.REDIRECT_URL,
    },
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  });

  const { access_token: accessToken, refresh_token: refreshToken } = response.data;

  // Save the access token and refresh token to your database or session

  // Redirect the user back to your app
  res.redirect('/');
}

export default handler;
···

Use the ·LinkWithAmazon· component in your app to render the button and call the getShoppingList function when needed:
jsx