Registration

After completing a standard AVS LWA authentication flow, your device must use its LWA token to register with AIA and establish a shared secret.

AIA and your device will use this shared secret for encrypting and decrypting messages on all AIA-specific MQTT topics, except for those involved in connection management.

Getting Started

Protocol

AIA exposes a secure HTTP/1.1 endpoint for registration mechanics.

Your device must be able to connect over HTTP/1.1 for initial registration, then use MQTT for remaining AIA-specific communication, including connection management, capability assertion, and exchanging messages on other topics required by Alexa capabilities.

Note: Your device must be able to follow HTTP/1.1 redirects.

AIA Envelope

Registration mechanics are part of v1 of the AIA envelope, indicated in the endpoint URI.

Request

Method POST
URI https://api.amazonalexa.com/v1/ais/registration
Data Format JSON

Header Parameters

Parameter Description Value Type
Content-Type Specifies the format of the message.

Accepted Values: application/json		 string

Body

Sample Message

{
  "authentication": {
    "token": "{{STRING}}",
    "clientId": "{{STRING}}"
  },
  "encryption": {
    "algorithm": "{{STRING}}",
    "publicKey": "{{STRING}}"
  },
  "iot": {
    "awsAccountId": "{{STRING}}",
    "clientId": "{{STRING}}",
    "endpoint": "{{STRING}}"
  }
}

Parameters

Field Name Description Value Type
authentication Details about the device's Alexa authentication. object
authentication.
  token		 The LWA refresh token acquired from the device's authentication with Alexa. string
authentication.
  clientId		 The client ID associated with the LWA refresh token provided. string
encryption Details about how the device requires encryption to be done. See the Encryption section for more information. object
encryption.
  algorithm		 The way in which the device and AIA will compute the shared secret, using the Elliptic Curve Diffie-Hellman (ECDH) protocol with the prime number 2255 - 19 (Curve25519).

Accepted Values:
ECDH_CURVE_25519_32_BYTE: The 32-byte shared secret will be the direct 32-byte output of ECDH.
ECDH_CURVE_25519_16_BYTE_SHA256: The 16-byte shared secret will be the output of hashing the 32-byte output of ECDH by using the Secure Hash Algorithm 256 (SHA-256), employing HKDF with no salt and no info, and then truncating that hashed result to 16 bytes. 		string
encryption.
  publicKey		 A base64-encoded 32-byte public key generated by the device. AIA uses this value in the ECDH protocol to generate the shared secret.

Note: The publicKey is always 32 bytes, regardless of whether the algorithm specifies that the shared secret will ultimately be 16 or 32 bytes. 		string
iot Details about the device's AWS IoT connection. object
iot.
  awsAccountId		 Your AWS developer account ID. string
iot.
  clientId		 The client ID of the device as registered with AWS IoT. string
iot.
  endpoint		 The AWS IoT endpoint the device connects to. string

Success Response (HTTP 200)

HTTP Headers

Header Parameters

Parameter Description Value Type
Content-Type Specifies the format of the message.

Possible Values: application/json		 string

Body

Sample Message

{
  "encryption": {
    "publicKey": "{{STRING}}"
  },
  "iot": {
    "topicRoot": "{{STRING}}"
  }
}

Parameters

Field Name Description Value Type
encryption Details required for computing the shared secret for AIA message encryption. See the Encryption section for more information. object
encryption.
  publicKey		 A base64-encoded 32-byte public key generated by AIA. The device uses this value in the ECDH protocol to generate the shared secret.

Note: The publicKey is always 32 bytes, regardless of whether the device's requested algorithm specifies that the shared secret will ultimately be 16 or 32 bytes. 		string
iot Details about the device's AWS IoT connection. object
iot.
  topicRoot		 The MQTT topic path that precedes AIA-specific topics. string

Failure Response (HTTP 4xx and 5xx)

HTTP Headers

Header Parameters

Parameter Description Value Type
Content-Type Specifies the format of the message.

Possible Values: application/json		 string

Body

Sample Message

{
  "code": "{{STRING}}",
  "description": "{{STRING}}"
}

HTTP Response Codes and Body Parameters

HTTP Response Code code description
400
Bad Request		 INVALID_REQUEST "The request was malformed."

The device provided malformed JSON in the request body.
MISSING_PARAM "{{PARAMETER}} is required"

The device did not provide a required parameter in the request body.
INVALID_ENCRYPTION_ALGORITHM "The encryption algorithm provided is not supported by AIA"

The device provided a value for encryption.algorithm that AIA does not support.
INVALID_ENCRYPTION_DATA The description will contain additional information about the nature of the problem, such as whether the public key is too short or too long.

The device provided an encryption.publicKey value that does not adhere to the standards required by the declared encryption.algorithm.
401
Unauthorized		 INVALID_AUTHENTICATION_CREDENTIALS "Unable to authenticate request", with additional information passed back by LWA.

The device provided invalid LWA parameters or values.
403
Forbidden		 INVALID_AWS_ACCOUNT "The AWS IoT account provided does not support AIA"

The device provided an iot.awsAccountId that is not on the AIA allow list.
INVALID_IOT_ENDPOINT "The AWS IoT endpoint provided cannot be accessed by AIA", with additional information passed back by AWS IoT.

The device provided an iot.endpoint that AIA does not have permission to connect to.
500
Internal Server Error		 INTERNAL_SERVER_ERROR "Internal server error", with additional information, depending on the problem.

AIA cannot process a valid request due to an internal issue.