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.
AcceptGrant directives for each customer, make sure you have requested permission to send Alexa events in the developer console. Use the slider on the Send Alexa Events section of the PERMISSIONS page to indicate your skill will send asynchronous responses and/or change report events.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.
HTTP 403 Forbidden response from Alexa, or an error from LWA when you try to refresh the token. For more information, see Authenticate a Customer to Alexa with PermissionsProperties 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
AcceptGrant processingExample 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:
