Alexa.AuthorizationController Interface
Implement the Alexa.AuthorizationController
interface in your Alexa skill for connected vehicles to request credentials from a user before you handle a directive, such as starting a car or unlocking a car door. For details, see Connected Vehicle Skills for Alexa.
The AuthorizationController
interface is different than other Alexa interfaces in that you aren't directly supporting voice user interactions with Alexa. Instead, you are asking Alexa to obtain credentials from the user. The AuthorizationController
interface defines no properties, and doesn't participate in state or change reporting. You attach one instance of the AuthorizationController
to one or more other interfaces in your discovery response.
For the list of languages that the AuthorizationController
interface supports, see List of Alexa Interfaces and Supported Languages.
Authorization workflow
When a user requests an action, such as unlocking their car, that has an AuthorizationController
attached to it, the workflow is the following:
- Alexa sends the usual directive to your skill, for example
Alexa.PowerController.TurnOn
. - Your skill sends an
Alexa.AuthorizationController.ChallengeResponse
event to Alexa. For details, see ChallengeResponse event. - Alexa asks the user for their credentials.
- Alexa sends an
Alexa.AuthorizationController.Authenticate
directive to your skill that contains the credentials provided by the user. For details, see Authenticate directive. - Your skill validates the credentials.
- If the credentials are valid, send an
Alexa.AuthorizationController.AuthenticationResponse
event to Alexa that contains an authorization token. For details, see Authenticate response event. - Alexa sends the original directive to your skill, for example
Alexa.LockController.TurnOn
, with your authorization token in the header. - You proceed to handle the original directive as usual. For details, see the documentation for the interface, for example PowerController.
Currently the Alexa.AuthorizationController
interface supports the following interfaces:
The following example shows a sample conversation when the user requests a directive that requires authorization. In this example, "my car" is the name that the user assigned to their car.
Alexa, start my car.
What's your voice code for my car?
One two three four
The following example shows how the user can bypass authorization by providing their PIN in the original request.
Alexa, start my car with PIN 1234.
Discovery
You describe endpoints that support Alexa.AuthorizationController
using the standard discovery mechanism described in Alexa.Discovery. Set both retrievable
and proactivelyReported
to false for the Alexa.AuthorizationController
interface.
Discover response example
The following example shows a Discover.Response
message for a car that supports the PowerController interface for turning the car on and off. The Alexa.AuthorizationController
interface is attached to the .
For the full list of recommended interfaces for a car, see Interfaces for connected vehicle skills.
For a more complete Discover.Response
example, see Discovery for connected vehicle skills.
{
"event": {
"payload": {
"endpoints": [
{
"endpointId": "<unique ID of the vehicle endpoint>",
"additionalAttributes": {
"serialNumber": "<the serial number of the vehicle>"
},
"endpointResources": {
"manufacturerName": {
"@type": "text",
"value": {
"text": "<the manufacturer name of the vehicle>",
"locale": "en-US"
}
},
"description": {
"@type": "text",
"value": {
"text": "<a description that appears in the Alexa app>",
"locale": "en-US"
}
},
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "<device name that appears in the Alexa app, such as car>",
"locale": "en-US"
}
},
{
"@type": "text",
"value": {
"text": "<additional device name, such as smart car>",
"locale": "en-US"
}
}
]
},
"displayCategories": ["VEHICLE"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.AuthorizationController",
"version": "1.0",
"properties": {
"supported": [],
"proactivelyReported": false,
"retrievable": false
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}
]
}
}
}
ChallengeResponse event
After Alexa sends you a directive, send a ChallengeResponse
event to request credentials from the user before proceeding with the directive. You identify the interfaces and directives that require authorization in your discovery response.
Authenticate directive payload details
Field | Description | Type | Required |
---|---|---|---|
preferredPolicy |
The type of credentials to request. The only valid value is FOUR_DIGIT_VOICE_PIN_RECOGNITION_BY_3P . |
String | Yes |
ChallengeResponse event example
{
"event": {
"header": {
"namespace": "Alexa.AuthorizationController",
"name": "ChallengeResponse",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "1.0"
},
"endpoint":{
"endpointId": "<endpoint id>"
},
"payload": {
"preferredPolicy": "FOUR_DIGIT_VOICE_PIN_RECOGNITION_BY_3P"
}
}
}
Directives
Authenticate directive
Support the Authenticate
directive so that users can provide a PIN code to authorize directives, such as unlocking their car.
Authenticate directive payload details
Field | Description | Type |
---|---|---|
authentication |
The credentials provided by the user. | Object |
authentication.type |
The type of credentials. The only valid type is FOUR_DIGIT_PIN . |
String |
authentication.value |
The PIN code provided by the user. | String |
Authenticate directive example
The following example illustrates an Authenticate
directive that Alexa sends to your skill.
{
"directive": {
"header": {
"namespace": "Alexa.AuthorizationController",
"name": "Authenticate",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<an OAuth2 bearer token>"
},
"endpointId": "<endpoint id>",
"cookie": {}
},
"payload": {
"authentication": {
"type": "FOUR_DIGIT_PIN",
"value": "1234"
}
}
}
}
Authenticate response event
If you validate the credentials provided by the user in an Authenticate
directive successfully, respond with an Alexa.AuthorizationController.AuthenticationResponse
event that contains an authorization token. Alexa then resends the original directive that triggered the authentication request, with your authorization token in the header.
Authenticate response event example
{
"event": {
"header": {
"namespace": "Alexa.AuthorizationController",
"name": "AuthenticationResponse",
"messageId": "<message id>",
"correlationToken": "<an opaque correlation token>",
"payloadVersion": "3"
},
"endpoint":{
"endpointId": "<endpoint id>"
},
"payload": {
"authToken": "<a Base64url-encoded token>"
}
}
}
Authenticate directive error handling
If you validate the credentials provided by the user in an Authenticate
directive successfully, respond with an Alexa.AuthorizationController.ErrorResponse event. You can also respond with a generic Alexa.ErrorResponse event if your error is generic, and not specific to authorization.