Request Access to the Alexa Event Gateway

To send events to the Alexa event gateway, your smart home skill must implement an OAuth 2.0 exchange with the Login with Amazon (LWA) OAuth server for each customer that enables your skill. This exchange gives your skill access to the event gateway on behalf of the customer. Later, you provide the customer access token in events and asynchronous responses to the Alexa event gateway. This token authenticates your smart home skill with the Alexa event gateway endpoint and identifies the Amazon customer to Alexa.

Follow these guidelines to authenticate your smart home skill with the Amazon customer account and manage the access tokens.

Event gateway authorization flow

To start the Alexa event gateway authorization flow, Alexa sends an Alexa.Authorization.AcceptGrant directive to your smart home skill. The directive includes the bearer token that Alexa obtained during account linking. You use the bearer token to identify the customer in your system. The directive also includes an authorization code. You use the authorization code, along with your skill client ID and client secret, to obtain access for the customer from the LWA OAuth server. LWA exchanges these credentials for access and refresh tokens. You must store these tokens for each customer. You use the access token to send events to the Alexa event gateway. Every sixty minutes, you use the refresh token to request new tokens from LWA.

The following image shows the OAuth 2.0 messaging flow.

Each time you send events and asynchronous responses on behalf of that customer, you include the access token in the scope of the message to the event gateway.

Implement the authorization flow

Add code to the skill code in your Lambda function to handle the Alexa.Authorization.AcceptGrant directive, request tokens from LWA, and store the tokens for each customer.

Handle the AcceptGrant directive

The following example shows an Alexa.Authorization.AcceptGrant directive that Alexa sends to your skill. The grant.code is the authorization code that you use to request access tokens from LWA. The grantee.token identifies the customer in your system. Alexa received this access token during account linking.

{
  "directive": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant",
      "messageId": "Unique version 4 UUID",
      "payloadVersion": "3"
    },
    "payload": {
      "grant": {
        "type": "OAuth2.AuthorizationCode",
        "code": "someAuthCode"
      },
      "grantee": {
        "type": "BearerToken",
        "token": "someAccessToken"
      }
    }
  }
}

Request access tokens from LWA

To start the access token flow with LWA, you send a Get access token with authorization code REST API request to LWA.

On success, the response includes the bearer access token, the refresh token, and the number of seconds before the access token becomes invalid. Store these tokens with the grantee access token so that you can always associate the tokens with the customer.

Authorization example

The following example handles the Alexa.Authorization.AcceptGrant directive and requests access tokens from LWA.

Show/hide sample code

"""
Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
SPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0
Licensed under the Amazon Software License  http://aws.amazon.com/asl/
"""
import json
import logging
import urllib.request
import urllib.parse
from urllib.error import HTTPError

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

# TODO: Update with your Client Id for calling the Login with Amazon (LWA) API.
client_id = "Your Client Id"
# TODO: Update with your Client Secret for calling the LWA API.
client_secret = "Your Client Secret"
# TODO: Update with your Endpoint Id.
endpoint_id = "device_id"


def handle_accept_grant(alexa_request):
    auth_code = alexa_request["directive"]["payload"]["grant"]["code"]
    message_id = alexa_request["directive"]["header"]["messageId"]

    # Use the Login With Amazon API to get access and refresh tokens from an auth code.
    lwa_token_url = "https://api.amazon.com/auth/o2/token"

    data = urllib.parse.urlencode(
        {
            "grant_type": "authorization_code",
            "code": auth_code,
            "client_id": client_id,
            "client_secret": client_secret
        }
    ).encode("utf-8")

    headers = {
        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8"
    }

    url_request = urllib.request.Request(lwa_token_url, data, headers, "POST")

    try:
        with urllib.request.urlopen(url_request) as response:
            """
            Response will contain the following:
            - access_token: Used in events and asynchronous responses to directives that you send to the Alexa event gateway.
            - refresh_token: Used to obtain a new access_token from LWA when this one expires.
            - token_type: Expected token type is Bearer.
            - expires_in: Number of seconds until access_token expires (expected to be 3600, or one hour).
            """
            lwa_tokens = json.loads(response.read().decode("utf-8"))

            # TODO: Save the LWA tokens in a secure location, such as AWS Secrets Manager.
            logger.info("Success!")
            logger.info(f"access_token: {lwa_tokens['access_token']}")
            logger.info(f"refresh_token: {lwa_tokens['refresh_token']}")
            logger.info(f"token_type: {lwa_tokens['token_type']}")
            logger.info(f"expires_in: {lwa_tokens['expires_in']}")
    except HTTPError as http_error:
        logger.error(f"An error occurred: {http_error.read().decode('utf-8')}")

        # Build the failure response to send to Alexa
        response = {
            "event": {
                "header": {
                    "messageId": message_id,
                    "namespace": "Alexa.Authorization",
                    "name": "ErrorResponse",
                    "payloadVersion": "3"
                },
                "payload": {
                    "type": "ACCEPT_GRANT_FAILED",
                    "message": "Failed to retrieve the LWA tokens from the user's auth code."
                }
            }
        }
    else:
        # Build the success response to send to Alexa
        response = {
            "event": {
                "header": {
                    "namespace": "Alexa.Authorization",
                    "name": "AcceptGrant.Response",
                    "messageId": message_id,
                    "payloadVersion": "3"
                },
                "payload": {}
            }
        }

    logger.info(f"accept grant response: {json.dumps(response)}")

    return response

def lambda_handler(request, context):
    logger.info(f"request: {request}")

    namespace = request["directive"]["header"]["namespace"]
    name = request["directive"]["header"]["name"]

    if namespace == "Alexa.Authorization" and name == "AcceptGrant":
        return handle_accept_grant(request)

Store tokens by customer and region

Store the access and refresh tokens with the grantee access token so that you can always associate the tokens with the customer. Store the tokens in a secured location, such as Amazon Web Services (AWS) DynamoDB or a secure token store in your device cloud.

If you offer your skill in multiple geographical regions, you must configure Lambda functions in each of those regions. For example, if you offer a skill that sends events in the US and the UK, you must configure Lambdas for both North America and Europe. Alexa sends the AcceptGrant directive for a US customer to your skill's North America Lambda function. You complete the authorization flow with LWA and store the token for that customer so that your skill's North America Lambda function can access it. You send events for that customer to the North American gateway endpoint. For a UK customer, Alexa sends the AcceptGrant to the Lambda function configured for Europe and you store and send events to the European endpoint.

If a customer moves between geographic regions, they have to re-enable and relink their skill. Then, your skill can change storage location of the associated customer information.

Respond to the AcceptGrant request

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 messages that your skill sends to the Alexa event gateway. Include the bearer access token in the HTTP Authorization header and in the endpoint.scope in the body of the message. For details, see Send Events.

Refresh tokens before expiration

If you send a message to the Alexa event gateway with an expired token, Alexa sends an HTTP 401 Unauthorized response. As a best practice, before the access token expires, use the refresh token to request new access and refresh tokens from LWA. An access token typically expires after 60 minutes. To refresh the token, use the Refresh access token operation.

On success, the response includes the bearer access token, the refresh token, and the number of seconds before the access token becomes invalid. Store these tokens with the grantee access token so that you can always associate the tokens with the customer.

Token refresh example

The following example requests new access tokens from LWA.

Show/hide sample code

"""
Copyright 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
SPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0
Licensed under the Amazon Software License  http://aws.amazon.com/asl/
"""
import json
import logging
import urllib.request
import urllib.parse
from urllib.error import HTTPError

logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

# TODO: Update with your refresh token, or a call that retrieves your refresh token from a secure location.
refresh_token = "Your Refresh Token"
# TODO: Update with your Client Id for calling the Login with Amazon (LWA) API.
client_id = "Your Client Id"
# TODO: Update with your client secret for calling the LWA API.
client_secret = "Your Client Secret"

# The Login With Amazon API endpoint
lwa_token_url = "https://api.amazon.com/auth/o2/token"

data = urllib.parse.urlencode(
    {
        "grant_type": "refresh_token",
        "refresh_token": refresh_token,
        "client_id": client_id,
        "client_secret": client_secret
    }).encode("utf-8")

headers = {
    "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8"
}

request = urllib.request.Request(lwa_token_url, data, headers, "POST")

try:
    with urllib.request.urlopen(request) as response:
        """
        Response will contain the following:
        - access_token: Used in events and asynchronous responses to directives that you send to the Alexa event gateway.
        - refresh_token: Used to obtain a new access_token from LWA when this one expires.
        - token_type: Expected token type is Bearer.
        - expires_in: Number of seconds until access_token expires (expected to be 3600, or one hour).
        """
        lwa_tokens = json.loads(response.read().decode("utf-8"))

        # TODO: Save the new LWA tokens in the same secure location.
        logger.info("Success!")
        logger.info(f"access_token: {lwa_tokens['access_token']}")
        logger.info(f"refresh_token: {lwa_tokens['refresh_token']}")
        logger.info(f"token_type: {lwa_tokens['token_type']}")
        logger.info(f"expires_in: {lwa_tokens['expires_in']}")
except HTTPError as http_error:
    logger.error(f"An error occurred: {http_error.read().decode('utf-8')}")

Test the authentication flow

Complete the following procedures to test the authentication flow.

To enable testing

1. Sign in to the Alexa developer console.
2. Find the skill you created during game registration.
3. Under ACTIONS, from the drop-down menu in your skill's row, select Edit.
4. Open the Test page.
5. If you haven't enabled testing, locate Test is disabled for this skill, and then, from the drop-down list, select Development for your skill testing stage.
6. If you have already enabled testing, locate Skill testing is enabled in, and then, from the drop-down list, select Development for your skill testing stage.

To start the authentication message flow

1. Sign in to the Alexa app on your mobile device with the same credentials as your Alexa developer account.
2. To find your skill in the Alexa app, tap More, and then tap Skills & Games.
3. In Skills & Games, tap Your Skills.
4. Scroll the skill types to the right, and then tap Dev.
5. Locate your skill name, and then tap ENABLE TO USE.
6. When Alexa prompts you, sign in to your Amazon developer account.
7. To allow access to the skill, tap Allow, and then tap CLOSE.

To view the skill log entries on the CloudWatch console

1. Sign in to the AWS management console.
2. Navigate to the CloudWatch console.
3. In the CloudWatch console, from the left menu under Logs, click Log groups.
4. Under Log group, to open the log stream for your skill, click /aws/lambda/my-smart-home-skill.
5. Under Log stream, to view logs for each directive that Alexa sent to the skill, click the log entry that you want to view.
6. Review the Alexa.Authorization.AcceptGrant directive from Alexa and the response from your skill.

Handle revocation

Alexa revokes the authorization grant for the following reasons:

• The customer disables your skill.
• A customer explicitly removes consent for the skill by accessing the Your Account > Manage Login with Amazon page of their Amazon account. When a customer removes consent, LWA revokes the authorization grant and denies your skill access to some or all resources associated with the customer account.

You must have logic in your skill 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.

Notification of a revoked grant

Alexa notifies you that a customer revoked the authorization grant in one of the following ways.

1. You can't refresh the token. In this scenario, when you try to refresh the token, LWA returns an invalid_grant error code. This error indicates that the customer revoked the authorization. For more details, see Refresh access token.
2. Alexa returns a 403 Forbidden status code in the HTTP response when the customer disables the skill or removes consent, but the token hasn't reached its expiration time.
   The following example shows an HTTP 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"
  }
}

Request new authorization codes

If you lose the access and refresh tokens associated with a customer or customers, you must request new ones by using the backfill process. To start the process, fill out the contact form on the Developer Support page. When you submit this form, Alexa resends AcceptGrant directives for each customer that enabled your skill.

Provide the following information in the contact form:

• 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 might receive up to 10 transactions per second. If you can't handle that rate, let us know in your contact request.

Until the backfill process completes, you must send synchronous events only. During the backfill process, asynchronous messages sent to the Alexa event gateway fail.

• Previous – Configure Permissions to Send Events
• Next – Send Events

Last updated: Aug 08, 2024