Request Access to the Alexa Event Gateway

To send events to the Alexa event gateway, your 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 skill with the Alexa event gateway endpoint and identifies the Amazon customer to Alexa.

Follow these guidelines to authenticate your 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 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.

Click to enlarge

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 secure request to https://api.amazon.com/auth/o2/token. For details, see LWA Access Token Request.

The following example shows an authentication request to LWA.

Copied to clipboard.

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type: authorization_code
&code: someAuthCode from AcceptGrant directive
&client_id: your.client.id
&client_secret: your.client.secret

Request body parameters

Parameter Description Type Required

grant_type

Type of access grant requested. You must set this parameter to authorization_code.

String

Yes

code

Authorization code from the AcceptGrant directive.

String

Yes

client_id

Client identifier for your skill from the Permissions menu in the Alexa developer console. For details, see Configure permissions to send events.

String

Yes

client_secret

Client secret for your skill from the Permissions menu in the developer console.

String

Yes

LWA access token response

On success, the HTTP 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.

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":"someAccessToken",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"someRefreshToken"
 }

The response body includes the following parameters. LWA encodes these parameters with the application/json media type.

Parameter Description Type Required

access_token

Token for the customer account.
Maximum size: 2048 bytes.

String

Yes

token_type

Type of token. Always set to bearer.

String

Yes

expires_in

Number of seconds before the access token becomes invalid.

Integer

Yes

refresh_token

Token that allows your skill to request a new access token from LWA.
Maximum size: 2048 bytes

String

Yes

Authorization example

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

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 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. For details about how to use the refresh token, see Request Refresh Tokens from LWA.

Request refresh example

The following example shows a refresh token request to LWA.

Copied to clipboard.

POST /auth/o2/token HTTP/1.1
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8

grant_type: refresh_token
&refresh_token: someRefreshToken
&client_id: your.client.id
&client_secret: your.client.secret

Request body parameters

Parameter Description Type Required

grant_type

Type of access grant requested. You must set this parameter to refresh_token.

String

Yes

refresh_token

Refresh token from the previous LWA response.

String

Yes

client_id

Client identifier for your skill from the Permissions menu in the Alexa developer console. For details, see Configure permissions to send events.

String

Yes

client_secret

Client secret for your skill from the Permissions menu in the developer console.

String

Yes

LWA refresh token response

On success, the HTTP response includes the bearer access token, the refresh token, and the number of seconds before the access token becomes invalid. For details, see LWA access token response. 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.

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.

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

There are two ways that Alexa notifies you that an authorization grant is revoked:

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

    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.

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.