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 Envelope
Request
- Header
- Body
Success Response (HTTP 200)
- HTTP Headers
- Body
Failure Response (HTTP 4xx and 5xx)
- HTTP Headers
- Body

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 2²⁵⁵ - 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.
403 Forbidden	`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.