Alexa.Authorization Interface

The Alexa.Authorization interface describes messages used to authorize asynchronous responses and change report events. For more information, see Authenticating a Customer to Alexa with Permissions.

Directives

AcceptGrant

The purpose of the AcceptGrant is to enable you to obtain credentials that identify and authenticate a customer to Alexa. You must implement this directive in order to send events to the Alexa event gateway. An AcceptGrant directive is sent by Alexa after a customer enables a smart home skill and goes through the account linking process or when an existing skill is upgraded to support asynchronous responses and/or proactive events.

Each AcceptGrant directive contains a grant, which contains authorization information, and a grantee, which identifies the customer who is authorized with the grant.

Example Request

{
  "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": "some-access-token"
      }
    }
  }
}

Payload details

Field Description Type Required
grant A polymorphic type that provides identifying information for a customer in Amazon Alexa systems. Polymorphic object Yes
grant.type Provides the type of grant specified, which determines the other fields for this object. string - only one supported value: OAuth2.AuthorizationCode Yes
grantee A polymorphic type that provides identifying information for a customer in a linked account service or system. polymorphic object Yes
grantee.type Provides the type of grantee specified, which determines the other fields for this object. string - only one supported value: BearerToken Yes

OAuth2.AuthorizationCode

The only supported descendant for grant is type OAuth2.AuthorizationCode, which provides a code property that specifies an OAuth2 authorization code. When you receive this authorization code grant, you must exchange it for an access token and refresh token using Login With Amazon (LWA). For more information, see [Smart Home Skill Authentication][smart-home-skill-authentication] and the LWA documentation.

BearerToken

Currently, the only supported descendant is the BearerToken type. BearerToken contains a single attribute, token, which contains the customer access token received by Alexa from the account linking process and identifies the customer in your system.

When the directive is sent using the HTTP protocol binding, the grantee bearer token is also provided in the Authorization header as follows:

Authorization: Bearer some-token-to-identify-customer

Properties and Events

For this interface, you can reply:

  • Synchronously, which means you send a Response to Alexa in from the Lambda function.

When you send a Response, you should include the state of reportable properties in the context of the message

Note that because this interface is synchronous only, the messages do not contain correlation tokens.

Reportable Properties

There are no reportable properties currently defined for this interface.

AcceptGrant.Response

If the AcceptGrant directive was successfully handled, you must respond synchronously with an AcceptGrant.Response event.

Example AcceptGrant.Response

{
  "event": {
    "header": {
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant.Response",
      "payloadVersion": "3"
    },
    "payload": {
    }
  }
}

ErrorResponse

If an error occurs while you are handling the AcceptGrant directive, you must respond synchronously with an ErrorResponse event.

If an error occurs for one of the following reasons, you should return an ACCEPT_GRANT_FAILED error type with a message that describes the error in more detail.

  • You were unable to call Login with Amazon to exchange the authorization code for access and refresh tokens
  • You were trying to store the access and refresh tokens for the customer, but were unable to complete the operation for some reason
  • Any other errors that occurred while trying to retrieve and store the access and refresh tokens

Example ACCEPT_GRANT_FAILED ErrorResponse

{
  "event": {
    "header": {
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "namespace": "Alexa.Authorization",
      "name": "ErrorResponse",
      "payloadVersion": "3"
    },
    "payload": {
      "type": "ACCEPT_GRANT_FAILED",
      "message": "Failed to handle the AcceptGrant directive because ..."
    }
  }
}

For other error cases, see Alexa.ErrorResponse.

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

Authorization