Alexa.Authorization Interface 3

Implement the Alexa.Authorization interface in your Alexa add-on to give your add-on access to the Alexa event gateway. Access to the gateway enables you to send asynchronous responses and proactive events, such as Alexa.ChangeReport, to Alexa. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Event gateway authorization

The purpose of the Alexa.Authorization.AcceptGrant directive is to enable you to obtain credentials that identify and authenticate a customer to Alexa. Alexa sends an AcceptGrant directive after a customer enables a smart home add-on and goes through the account linking process, or when you update an existing smart home add-on to support proactive events. The AcceptGrant directive contains the following information:

Alexa sends you an authorization code. Exchange the authorization code for an access token and refresh token by using Login With Amazon (LWA). For details, see the Get access token with authorization code operation and LWA Authorization Code Grant.
Alexa sends you the access token for the customer that Alexa received during the account linking process. Store the token, and use the token to identify the customer in your system.

Directives

The Alexa.Authorization interface defines the following directives.

AcceptGrant directive

Support the AcceptGrant directive so that you can obtain and store credentials that identify a customer to Alexa.

AcceptGrant directive example

The following example illustrates an AcceptGrant directive that Alexa sends to your add-on. Because this interface is synchronous, the message doesn’t contain a correlation token.

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

AcceptGrant directive payload

The following table shows the payload details for the AcceptGrant directive.

Property	Description	Type	Required
`grant`	Information that identifies a customer in Amazon Alexa systems.	Object	Yes
`grant.type`	Type of grant. Valid value: `OAuth2.AuthorizationCode`.	String	Yes
`grant.code`	Authorization code for the customer. Exchange the authorization code for an access token and refresh token by using the Login With Amazon (LWA) OAuth 2.0 server.	String	Yes
`grantee`	Information that identifies a customer in the linked-account service or system.	Object	Yes
`grantee.type`	Type of access token. Smart home add-ons support bearer token types only. For more details, see OAuth Access Token Types. Valid value: `BearerToken`.	String	Yes
`grantee.token`	The customer access token received by Alexa during the account linking process.	String	Yes

AcceptGrant response

If you handle an AcceptGrant directive successfully, respond with an AcceptGrant.Response. Because this interface is synchronous only, don’t include a correlation token. The following example shows an AcceptGrant.Response. The response doesn’t require a payload.

{
  "event": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant.Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "payloadVersion": "3"
    },
    "payload": {}
  }
}

AcceptGrant error handling

If you can’t handle an AcceptGrant directive successfully for one of the following reasons, respond with an Alexa.Authorization.ErrorResponse:

You’re unable to call LWA to exchange the authorization code for access and refresh tokens.
You’re unable to store the access and refresh tokens for the customer.
Any other error that occurs while you try to retrieve and store the access and refresh tokens.

For more general errors, respond with an Alexa.ErrorResponse event. The following example shows an Alexa.Authorization.ErrorResponse.

{
  "event": {
    "header": {
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "namespace": "Alexa.Authorization",
      "name": "ErrorResponse",
      "payloadVersion": "3"
    },
    "payload": {
      "type": "ACCEPT_GRANT_FAILED",
      "message": "Failed to handle the AcceptGrant directive because <your reason>"
    }
  }
}

Get Started

Connect Your Device to Alexa

Certify Your Device

Developer Reference

Event gateway authorization

Directives

AcceptGrant directive

AcceptGrant directive example

AcceptGrant directive payload

AcceptGrant response

AcceptGrant error handling

​Event gateway authorization

​Directives

​AcceptGrant directive

​AcceptGrant directive example

​AcceptGrant directive payload

​AcceptGrant response

​AcceptGrant error handling

​Related topics

Event gateway authorization

Directives

AcceptGrant directive

AcceptGrant directive example

AcceptGrant directive payload

AcceptGrant response

AcceptGrant error handling

Related topics