Alexa.AuthorizationController Interface 1.0

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. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

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:

• PowerController
• LockController
• ToggleController
• RangeController
• ModeController

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.

• English (All)

The following example shows how the user can bypass authorization by providing their PIN in the original request.

• English (All)

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 complete Discover.Response example, see Discovery for connected vehicle skills.

{
  "event": {
    "payload": {
      "endpoints": [
        {
          "endpointId": "Unique ID of the vehicle endpoint",
          "additionalAttributes":  {
            "serialNumber": "Serial number of the vehicle"
          },
          "endpointResources": {
            "manufacturerName": {
              "@type": "text",
              "value": {
                "text": "Manufacturer name of the vehicle",
                "locale": "en-US"
              }
            },
            "description": {
              "@type": "text",
                "value": {
                  "text": "Description to be shown 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"
            }
          ]
        }
      ]
    }
  }
}

Directives and events

The Alexa.AuthorizationController interface defines the following directives and events.

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

Authenticate directive example

The following example illustrates an Authenticate directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.AuthorizationController",
      "name": "Authenticate",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Unique ID of the endpoint",
      "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.

The following example shows an Authenticate response.

{
  "event": {
    "header": {
      "namespace": "Alexa.AuthorizationController",
      "name": "AuthenticationResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "Unique ID of endpoint"
    },
    "payload": {
      "authToken": "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.

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.

ChallengeResponse event example

{
  "event": {
    "header": {
      "namespace": "Alexa.AuthorizationController",
      "name": "ChallengeResponse",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "1.0"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID"
    },
    "payload": {
      "preferredPolicy": "FOUR_DIGIT_VOICE_PIN_RECOGNITION_BY_3P"
    }
  }
}

ChallengeResponse event payload details

Related topics

• VehicleData