Your Alexa Consoles
Sign In
Sign In

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": "abc-123-def-456",
      "payloadVersion": "3"
    },
    "payload": {
      "grant": {
        "type": "OAuth2.AuthorizationCode",
        "code": "VGhpcyBpcyBhbiBhdXRob3JpemF0aW9uIGNvZGUuIDotKQ=="
      },
      "grantee": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      }
    }
  }
}

Payload details

Field Description Type Required
grant A polymorphic type that provides identifying information for a customer in Amazon Alexa systems. Polymorphic object, currently with one supported child type: OAuth2.AuthorizationCode Yes
grant.type Provides the type of grant specified, which determines the other fields for this object. String specifying OAuth2.AuthorizationCode Yes
grant.code An authorization code for the customer. String Yes
grantee A polymorphic type that provides identifying information for a customer in a linked account service or system. Polymorphic object, currently with one supported child type BearerToken. Yes
grantee.type Provides the type of grantee specified, which determines the other fields for this object. String, specifying BearerToken. Yes
grantee.token Provides the customer access token received by Alexa from the account linking process. String Yes

OAuth2.AuthorizationCode type

The only supported child type for a grant is the OAuth2.AuthorizationCode type. When you receive an OAuth2.AuthorizationCode, grant also contains a code attribute that contains an OAuth2 authorization code. Exchange the authorization code for an access token and refresh token using Login With Amazon (LWA). For more information, see Authenticate a Customer to Alexa with Permissions and the LWA documentation.

BearerToken type

Currently, the only supported child type for grantee is the BearerToken type. When you receive a BearerToken type, grantee also contains a token attribute, which contains the customer access token received by Alexa from the account linking process. Use the token to identify the customer in your system.

Properties and Events

For this capability, you must reply:

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

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

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

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": "abc-123-def-456",
      "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": "abc-123-def-456",
      "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