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're 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:

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

Alexa, démarre ma voiture.
Quel est votre code vocal pour ma voiture?
Un deux trois quatre

Alexa, arranca mi coche.
¿Cuál es su código de voz para mi coche?
Uno dos tres cuatro

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.

Alexa, démarre ma voiture avec le code 1234.

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

Copied to clipboard.

{
  "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

Property 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": "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.

Copied to clipboard.

{
  "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

Copied to clipboard.

{
  "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

Property Description Type Required
preferredPolicy The type of credentials to request. The only valid value is FOUR_DIGIT_VOICE_PIN_RECOGNITION_BY_3P. String Yes

Last updated: Feb 08, 2023