Alexa.Authorization Interface

Implement the Alexa.Authorization interface in your Alexa skill so you can send asynchronous responses or proactive messages such as change reports to the Alexa event gateway.

Overview

The purpose of the Alexa.Authorization.AcceptGrant directive is to enable you to obtain credentials that identify and authenticate a user to Alexa.

Alexa sends an AcceptGrant directive after a user enables a Smart Home skill and goes through the account linking process, or when you update an existing skill to support proactive change reporting events.

The AcceptGrant directive contains the following:

  • 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 LWA documentation.

  • Alexa sends you the access token for the user that Alexa received during the account linking process. Store the token, and use the token to identify the user in your system.

Directives

AcceptGrant directive

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

AcceptGrant directive example

The following example illustrates an AcceptGrant directive that Alexa sends to your skill. Because this interface is synchronous only, the message doesn't contain a correlation token.

{
  "directive": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant",
      "messageId": "<message id>",
      "payloadVersion": "3"
    },
    "payload": {
      "grant": {
        "type": "OAuth2.AuthorizationCode",
        "code": "VGhpcyBpcyBhbiBhdXRob3JpemF0aW9uIGNvZGUuIDotKQ=="
      },
      "grantee": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      }
    }
  }
}

AcceptGrant directive payload details

Field Description Type
grant Information that identifies a user in Amazon Alexa systems. Object
grant.type The type of grant. Currently, the only valid value is OAuth2.AuthorizationCode. String
grant.code An authorization code for the user. String
grantee Information that identifies a user in a linked account service or system. Object
grantee.type The type of grantee. Currently, the only valid value is BearerToken. String
grantee.token The user access token received by Alexa during the account linking process. String

AcceptGrant response event

If you handle an AcceptGrant directive successfully, respond with an AcceptGrant.Response event. Because this interface is synchronous only, the message doesn't contain a correlation token.

AcceptGrant response event example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant.Response",
      "messageId": "<message id>",
      "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 event:

  • You are unable to call Login with Amazon to exchange the authorization code for access and refresh tokens.
  • You are unable to store the access and refresh tokens for the user.
  • 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.

AcceptGrant error response event example

Copied to clipboard.

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