Your Alexa Dashboards Settings

Authenticate a Customer to Alexa with Permissions

You must authenticate a customer in your system with Alexa when you respond asynchronously to a directive or when you send change reports to the Alexa event gateway. You provide the authentication information a scope in the event message. This document describes the process for obtaining and providing the authentication information for a customer when you send messages to Alexa.

Getting authorization

When a customer first enables your skill that has permission to send messages to the Alexa event gateway, or a previously enabled skill is migrated from v2 to v3, Alexa sends a message called an AcceptGrant directive for each customer. An AcceptGrant includes a bearer token that identifies the customer in your system and an authorization code so you can obtain credentials for that customer with Alexa. You use the authorization code provided to call Login with Amazon (LWA) and retrieve access and refresh tokens.

The following image shows the process of authenticating a customer and sending messages on their behalf.

Each time you send an asynchronous response or a device state change report on behalf of that customer, you include the access token in the scope of the message to the event gateway. The structure of the message is the same as for a synchronous response, but you send the messages to the event gateway.

NOTE: You should always follow OAuth 2 best practices when storing and sending authentication tokens. This means that tokens and other identifying information should be stored and exchanged in a secure manner.

There are a couple important notes about this process:

  1. You should exchange the authorization code for the access and refresh tokens right away, as the authorization code has a limited validity period (a few minutes). Once the authorization code expires, the customer must disable and enable the skill again, so a new authorization code is generated and sent to your Lambda function with the AcceptGrant directive.

  2. You must store the access and refresh tokens for a customer and include the access token in each asynchronous or change report event. Before the token expires, you should use the stored refresh token to get new access and refresh tokens. Note that per LWA guidelines, access tokens are valid for 60 minutes.

In addition, when a skill is migrated from v2 to v3, and you have requested permission to send events to the Alexa event gateway, there is a backfill process and you will receive an AcceptGrant directive for every customer that has enabled your skill. Be prepared to receive these messages and complete the authentication process.

Steps for asynchronous message authentication

  1. Sign in to the developer portal and select the skill.
  2. On the Configurations page for your skill, make sure you have added an ARN number to associate the skill with a Lambda function.
  3. In the Permissions section, select Send Alexa Events to indicate your skill will send asynchronous responses and state report events.
  4. Click Save
  5. In the Alexa Skill Messaging section that appears, note the clientId and clientSecret in this section, as you will need these values to request an access token for a customer. Following is an image that shows an example:
  1. Add code in your Lambda function to handle an AcceptGrant directive. You will receive one every time your skill is enabled by a customer. Following is an example of the AcceptGrant message. For more details about the AcceptGrant message, see the Alexa.Authorization interface. A skill needs to be enabled and account linked to an account in your system before the AcceptGrant message is sent to your skill. See Enable testing for your skill for more details.
{
  "directive": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "payloadVersion": "3"
    },
    "payload": {
      "grant": {
        "type": "OAuth2.AuthorizationCode",
        "code": "VGhpcyBpcyBhbiBhdXRob3JpemF0aW9uIGNvZGUuIDotKQ=="
      },
      "grantee": {
        "type": "BearerToken",
        "token": "bearer-token-representing-user"
      }
    }
  }
}
  • Return an AcceptGrant.Response for each AcceptGrant directive you receive. If an error occurs, you should return an ACCEPT_GRANT_FAILED error response.

Enable testing for the skill

To start the authentication message flow:

  1. Enable the skill for testing on the Test page in the developer portal.
  2. In the Alexa app, enable and account link the skill. Upon successful linking, the AcceptGrant directive is sent with a valid authorization code.
  3. Use the value in the code field of the AcceptGrant directive to send an access token request to LWA to retrieve an access token. Send the secure HTTP POST to https://api.amazon.com/auth/o2/token with the parameters listed in the table. For more information, see the Access Token Request topic in the LWA documentation.
Parameter Description
grant_type REQUIRED. The type of access grant requested. Must be authorization_code.
code REQUIRED. The value for code provided in the AcceptGrant directive.
client_id REQUIRED. The client identifier. Will be provided in the Permissions section of the developer portal.
client_secret REQUIRED. The client secret. Will be provided in the Permissions section of the developer portal.

Note that although the LWA documentation is ambiguous about whether a redirect_uri is required, it is not and you should not include it in your request.

For example:

 POST /auth/o2/token HTTP/l.l
 Host: api.amazon.com
 Content-Type: application/x-www-form-urlencoded;charset=UTF-8
 grant_type=authorization_code&code=SplxlOBezQQYbYS6WxSbIA&client_id=smarthome&client_secret=Y76SDl2F
  • Store the bearer token and refresh token in the response. You need to make sure you can always associate the tokens with that customer, which is identified by the Grantee section of the AcceptGrant message. Following is an example response:
 HTTP/l.l 200 OK
 Content-Type: application/json;charset UTF-8
 Cache-Control: no-store
 Pragma: no-cache
 {
    "access_token":"Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"Atzr|IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeX..."
 }
  • Use the access_token value in the scope of messages to the Alexa event gateway. The endpoints are:

  • North America: https://api.amazonalexa.com/v3/events
  • Europe: https://api.eu.amazonalexa.com/v3/events
  • Far East: https://api.fe.amazonalexa.com/v3/events

Example message including authorization token specified as an HTTP Authorization header and a bearer token in the scope of the message:


POST api-amazonalexa.com
Authorization: Bearer Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...
Content-Type: application/json

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.LockController",
      "name": "lockState",
      "value": "LOCKED",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 1000
    } ]
  },
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR..."
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

Requesting new authorization codes

If you lose the access and refresh tokens associated with a customer or customers, you will need to request new ones using our backfill process. Use the contact form on the Developer Support page to start the process. When you submit this form, you will be added to a list and we will resend AcceptGrant directives for each customer that has enabled your skill.

Provide the following information:

  • Email address: Provide an email address for a developer account associated with your skill.
  • Subject: Alexa
  • Message: Request an authentication backfill for your skill, and provide your skill ID.

Backfill requests will be processed once a week, and you should be prepared to receive authorization codes for every customer that has enabled your skill. You could receive up to 10 transactions per second, and if you cannot handle that number of messages, you should let us know in your contact request.

You must send synchronous events until the backfill completes as any responses sent to the Alexa event gateway will fail.

Notification of expired token and using the refresh token

If you send a message to the Alexa event gateway with an expired token, you will receive an HTTP 401 Unauthorized response. For more information, see Error responses from the gateway As a best practice, before the access token expires, you should use the refresh token to request new access and refresh tokens from LWA. Per LWA guidelines, a token expires after an hour. For details about how to use the refresh token, see Using Refresh Tokens in the LWA documentation.

Revoking authorization

Alexa revokes the authorization grant for the following reasons:

  • A skill is disabled by the customer
  • A customer explicitly removes consent for the skill by accessing the Your Account > Manage Login with Amazon page of their Amazon account.

Notification of a revoked grant

There are two main ways you are notified that a authorization grant has been revoked:

  • You get a HTTP 403 when you send an event with a token that has not expired. This happens when the skill is disabled or a customer removes consent, but the token you obtained has not reached its expiration time.

Example 403 Response

HTTP/l.l 403 Forbidden
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma: no-cache
{
 "error":"skill_not_enabled",
 "error_description":"The user does not have a valid enablement for your skill"
}
  • You are not able to refresh a token. In this situation, when you try to refresh the token, you get an invalid_grant error code from LWA. This is a permanent state and indicates that the authorization has been revoked by the customer. For more information, see the Access Token Errors section of the LWA documentation.

When a customer removes consent, the authorization grant is revoked and your skill is denied access to some or all resources associated with the customer account. You must have logic in your skill and supporting systems to stop sending events that rely on the grant, such as asynchronous messages to the event gateway. Other parts of the skill must function as normal.