Alexa.Authorization.AcceptGrant Interface
Implement the Alexa.Authorization.AcceptGrant
interface in your Alexa skill so that you can send asynchronous responses or proactive events, such as Alexa.ChangeReport
, to the Alexa event gateway.
Event gateway authorization
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 smart home skill 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 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.
HTTP 403 Forbidden
response from Alexa, or an error from LWA when you try to refresh the token.AcceptGrant
directives for each user, 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 sends messages to the Alexa event gateway.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, 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": "someAuthCode"
},
"grantee": {
"type": "BearerToken",
"token": "someAccessToken"
}
}
}
}
AcceptGrant directive payload
The following table shows the payload details for the AcceptGrant
directive.
Property | Description | Type | Required |
---|---|---|---|
|
Information that identifies a user in Amazon Alexa systems. |
Object |
Yes |
|
Type of grant. |
String |
Yes |
|
Authorization code for the user. |
String |
Yes |
|
Information that identifies a user in the linked-account service or system. |
Object |
Yes |
|
Type of grantee. |
String |
Yes |
|
The user 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 a AcceptGrant.Response
. The response doesn't require a payload.
{
"event": {
"header": {
"namespace": "Alexa.Authorization",
"name": "AcceptGrant.Response",
"messageId": "a 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 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
processing, the user can't enable your skill.The following example shows an Alexa.Authorization.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 <your reason>"
}
}
}