Get an Access Token for SMAPI

When you make a request to the Alexa Skill Management API (SMAPI), you must provide an access token in the header of the request. To use SMAPI, you need to know what the access token represents, where to put it in the request, and how to get an access token. The way that you get an access token depends on your role in the skill-building process.

This page describes how to create a Login With Amazon (LWA) access token by using the Alexa Skills Kit Command Line Interface (ASK CLI). If you want to create your own tool to generate LWA access tokens, see Authorization Code Grant in the LWA documentation.

What the access token represents

An access token signifies that a resource owner has given a client permission to perform a list of operations on a set of resources. With SMAPI, the roles are as follows:

  • Resource – The resource can be a skill or something that a skill uses: an interaction model, in-skill product, account linking information, and so on.
  • Resource owner – The resource owner is the Amazon developer account that the resource belongs to. Each Amazon developer account has a vendor ID. To find your vendor ID, log in to your Amazon developer account, and then go to Customer Details.
  • Client – The client is the developer, tool, or organization that needs permission to be able to perform a list of operations on the skill by using SMAPI. The client can be the ASK CLI (which uses SMAPI under the hood), another skill-building tool, or a developer who uses SMAPI to access the skill. The client ID and client secret of the security profile identify the client. The client configures the ID and secret in the Login with Amazon (LWA) console by using their Amazon developer account.
  • Operations – Operations are the actions that the client wants permission to perform on the skill. Examples of operations are create, read, update, delete, and so on. In the context of access tokens for SMAPI, scopes identify operations.

After you get the access token, you must keep the access token current. You keep the access token current by obtaining a refresh token to request a new access token when the access token expires in one hour.

Where to provide the access token

When you make an HTTPS request to SMAPI, you provide the access token as the bearer token in the Authorization header of the request. The following example, which is a request to get a skill manifest, shows where the access token fits into the request.

GET /v1/skills/{skillId}/stages/{stage}/manifest
Host: api.amazonalexa.com
Content-Type: application/json
Authorization: "Bearer {LWA Access Token}"

How to get an access token

You can get an access token in the following ways, depending on your role in the skill-building process:

  • You're both the resource owner and the client – For example, you're an independent developer and you want to use SMAPI to work on skills that you create. To generate an access token, you can use the ASK CLI. For instructions, see Get an access token when you're both the resource owner and the client.
  • You're the client, and someone else is the resource owner – For example, you're an organization or you built a skill-building tool for developers who create skills for you under their own Amazon developer account. To generate an access token, you first send the resource owner an authorization URL that the resource owner uses to log in to LWA. After the resource owner successfully logs in, LWA returns an authorization code, which you use to generate an access token by using the ASK CLI. For instructions, see Get an access token when you're the client, and someone else is the resource owner. If you want to create your own tool to generate LWA access tokens, see Authorization Code Grant in the LWA documentation.
  • You're the resource owner, and someone else is the client – For example, you're a developer who creates skills by using a skill-building tool, or for an organization by using your own Amazon developer account. To get an access token, you first must log in at an authorization URL that the client sends you. After you log in, the client sends you an access token. For instructions, see Get an access token when you're the resource owner, and someone else is the client.

Get an access token when you're both the resource owner and the client

In this simplest case, you want to use SMAPI to work on skills that you create under your own Amazon developer account.

To get an access token for yourself

  1. Configure a security profile with LWA.
  2. Get the client ID and client secret of the security profile from the LWA console.
  3. Choose the operations, also called scopes, that you're asking for permission to perform with SMAPI.
  4. Use the LWA client ID, client secret, and scopes to generate an access token by using the ASK CLI.

Get an access token when you're the client, and someone else is the resource owner

In this case, you want to access skills that a resource owner creates under their own Amazon developer account. For example, you built a skill-building tool or are an organization for whom a developer creates skills. In the following procedure, the developer (resource owner) gives your tool permission to access their skills, and then your tool generates an access token.

This procedure describes how to create a Login With Amazon (LWA) access token by using the ASK CLI. If you want to create your own tool to generate LWA access tokens, see Authorization Code Grant in the LWA documentation.

To get an access token for a resource owner who has their own Amazon developer account

  1. Configure a security profile with LWA.
  2. Get the client ID and client secret of the security profile from the LWA console.
  3. Choose the operations, also called scopes, that you're asking for permission to perform with SMAPI.
  4. Use the ASK CLI util generate-lwa-tokens command with the --no-browser option as follows.
    ask util generate-lwa-tokens --no-browser <scopes> --client-id <client_ID> --client-confirmation <client_secret>
    For more information about this command, see generate-lwa-tokens in the ASK CLI Command Reference.
  5. Copy the authorization URL that the ASK CLI displays, and then send it to the resource owner.
    After the resource owner clicks the URL, logs in with their Amazon developer account credentials, and agrees to grant the requested permissions, the window displays an authorization code.
  6. Ask the developer to enter the displayed authorization code into your tool.
  7. Use the authorization code plus your own LWA client ID and client secret to generate an access token by using the ASK CLI.
  8. Give the access token to the resource owner so that the resource owner can use it in the header of the requests to SMAPI.

Get an access token when you're the resource owner, and someone else is the client

In this case, you're the resource owner, and you create skills for an organization or by using a skill-building tool. That is, the skills are under your Amazon developer account and the organization or tool will access your skills, given your permission.

To get an access token from an organization or tool

  1. If the organization didn't already send you an LWA URL, request it.
  2. Click the LWA URL that the organization sent you.
  3. Enter the username and password for your Amazon developer account.
    After you successfully log in, the organization sends you the access token that you can use with SMAPI.

Perform the following procedures to prepare for and generate an access token. The access token can be for yourself, for someone who creates skills for you, or someone who creates skills by using your tool.

Configure an LWA security profile to use with SMAPI

Before you can generate an access token by using the ASK CLI, you must first configure an LWA security profile.

To configure an LWA profile to use with SMAPI

  1. Go to the LWA console, and then log in with your Amazon developer account credentials.
  2. If you don't already have a security profile (that is, you don't see one or more security profiles listed on the page), click Create a New Security Profile, enter the required information, and then click Save.
  3. In the Login with Amazon Configurations list, find your security profile, click the gear icon, and then select Web Settings.
  4. On the bottom right, click Edit.
  5. In the Allowed Return URLs field, paste the following URLs:
    http://127.0.0.1:9090/cb
    https://ask-cli-static-content.s3-us-west-2.amazonaws.com/html/ask-cli-no-browser.html
    Make sure that you add these URLs to Allowed Return URLs, not Allowed Origins.
  6. At the bottom of the page, click Save.

Get the LWA client ID and client secret of the security profile

When you run the ASK CLI to generate the access token, the CLI prompts you to enter the client ID and client secret of the security profile that you created in LWA. You can get these credentials from the LWA console by completing the following procedure.

To get the client ID and client secret of your LWA security profile

  1. Go to the LWA console, and then log in with your Amazon developer account credentials.
  2. In the Login with Amazon Configurations list, find your security profile, click the gear icon, and then select Web Settings.
  3. Copy the Client ID and Client Secret.
    You need them when you run the ASK CLI to generate the access token.

Generate an access token

With the LWA client ID and client secret that you copied from your LWA security profile, and, optionally, a list of scopes that you want the access token to have permission to, you can generate an access token by using the ASK CLI.

To generate an access token by using the ASK CLI

  1. On the computer where you installed the ASK CLI, go to the command line, and then enter ask util generate-lwa-tokens.
    For more information about this command, see generate-lwa-tokens in the ASK CLI Command Reference.
  2. At the prompts, enter the LWA client ID and client secret that you copied from your LWA security profile.
  3. In the browser that opens, sign in with the username and password for your Amazon developer account.
    For many people, these are the same username and password that you use for your Amazon account.
  4. On the access page that opens, click Allow.

Operation scopes

When you create an access token by using the ASK CLI ask util generate-lwa-tokens command, you can optionally specify the operations, or scopes, that the access token permits access to. For SMAPI, you can choose one or more of the scopes from the following table. Make sure that you limit the scopes to only those operations that your skill needs.

Scope Some associated operations

alexa::ask:skills:read
  • List the vendor IDs associated with the Amazon developer account
  • Read skill details, excluding interaction models
  • Get skill status
  • Get list of skills

alexa::ask:skills:readwrite

All alexa::ask:skills:read permissions plus:

  • Create skills
  • Update skills
  • Enable skills
  • Read and update account linking information for skills
  • Submit to, and withdraw skills from, certification

alexa::ask:models:read
  • Read interaction models
  • Get build status for interaction models

alexa::ask:models:readwrite

All alexa::ask:models:read permissions plus:

  • Update interaction models

alexa::ask:skills:test

The following skill-testing operations:

  • Invoke a skill
  • Submit a simulation request
  • Get simulation status
alexa::ask:catalogs:read

Get a list of catalogs
alexa::ask:catalogs:readwrite

Update existing catalogs or create new catalogs
alexa::ask:subscriptions

Use the Skill Development Notifications API
alexa:skill_messaging

Use the Skill Messaging API
alexa::proactive_events

Use the Proactive Events API
alexa::devices:all:notifications:write

Use the Proactive Notifications API
Was this page helpful?

Last updated: Aug 07, 2024