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 in 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 for an enabled skill that migrated from v2 to v3, Alexa sends a message, called theAcceptGrant directive. An AcceptGrant includes a bearer token that identifies the customer in your system and an authorization code. You use the authorization code to obtain credentials for that customer. Use Login with Amazon (LWA) to 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 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.

To store and send authentication tokens in a secure manner, follow OAuth 2.0 best practices. Your skill must handle tokens and other identifying information as follows:

  1. Exchange the authorization code for the access and refresh tokens right away. 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 AWS 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. Access tokens are valid for 60 minutes. For details, see LWA Access Tokens,

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

Complete the following procedures to add asynchronous message authentication to your skill.

Enable Alexa event permissions

To indicate that your skill sends asynchronous responses and/or change report events, complete the following steps.

To enable permissions to send Alexa events

  1. Sign in to the Alexa developer console and select the skill.
  2. From the skill list, select your smart home skill, and then, in the dropdown under ACTIONS, select Edit.
  3. In the left pane, click PERMISSIONS.
  4. To enable permission to send Alexa events, toggle Send Alexa Events.
  5. Under Alexa Skill Messaging, note the Client Id and Client Secret.
    You use the Client Id and Client Secret values to request an access token for a customer.
    The following image shows the permissions toggle, and an example Client Id and Client Secret.
    Smart Home Permissions


Implement the authentication flow

After a customer enables your skill and completes account linking, Alexa sends an AcceptGrant directive to your skill. Add code in your Lambda function to handle the AcceptGrant directive and initiate authentication with LWA. For more details about the AcceptGrant message, see Alexa.Authorization.

The following example shows a AcceptGrant directive that Alexa sends to your skill.

{
  "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"
      }
    }
  }
}

To start the authentication flow with LWA, you send the secure HTTP POST request to https://api.amazon.com/auth/o2/token. For details, see LWA Access Token Request.

The following example shows an authentication request.

Copied to clipboard.

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

Request body parameter details

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 provided in the Permissions section of the developer console.
client_secret REQUIRED. The client secret provided in the Permissions section of the developer console.

The HTTP response includes the bearer token and refresh token. Store the bearer token and refresh token so that you can always associate the tokens with the customer, identified by the Grantee section of the AcceptGrant message.

The following example shows a successful authentication response.

 HTTP/1.1 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..."
 }

After authentication completes, return an AcceptGrant.Response. If an error occurs, return an ACCEPT_GRANT_FAILED error response.

Use the tokens in events to the Alexa gateway

Use the access_token value in the scope of messages that your skill sends 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

The following example shows an event to the Alexa Gateway. The message includes the authorization token specified as an HTTP Authorization header and a bearer token in the endpoint scope in the message.

POST /v3/events HTTP/1.1
Host: 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": {}
  }
}

Test the authentication flow

Complete the following procedures to test the authentication flow.

To start the authentication message flow

  1. On the Test page in the developer console, enable the skill for testing.
  2. In the Alexa app, enable and account link the skill.
    After successful linking, Alexa sends the AcceptGrant directive with a valid authorization code.

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.

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 details, see Event gateway error codes. As a best practice, before the access token expires, use the refresh token to request new access and refresh tokens from LWA. A token expires after an hour. For details about how to use the refresh token, see Using Refresh Tokens.

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/1.1 403 Forbidden
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close

{
  "header": {
    "namespace": "System",
    "name": "Exception",
    "messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
  },
  "payload": {
    "code": "SKILL_DISABLED_EXCEPTION",
    "description": "Skill is disabled. 3P needs to specifically identify that the skill is disabled by the customer so they can stop sending events for that customer"
  }
}

  • 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 details, see the Access Token Errors.

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.