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
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. |