func-api-devices-register-post

Description

Registers a FireFly device with FireFly-Cloud by creating a record in the firefly-devices DynamoDB table. Called by the HW-Reg application during the Cloud Registration step.

The request must include a valid one-time X-Registration-Key header. The function validates the key against the firefly-registration-keys table, then writes the device record (including the email of the user who generated the key as registered_by_email) and deletes the consumed key. Registration is idempotent: if the UUID already exists, the function returns 204 immediately without modifying the existing record.

This endpoint does not require a Cognito JWT — it is authenticated solely by the one-time registration key.

Invocation

Invoked by API Gateway on an HTTP POST /devices/register request.

Sequence Diagram

API Endpoints

Method	Path	Auth	Description
POST	/devices/register	Registration key (header)	Register a device

Request Headers

Header	Required	Description
X-Registration-Key	Yes	6-character one-time key generated by POST /registration-keys

Request Body

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "product_id": "FFC0806-2505",
  "product_hex": "0x08062505",
  "device_class": "controller",
  "public_key": "<base64-encoded uncompressed P-256 point>",
  "registering_application": "Hardware-Registration-and-Configuration",
  "registering_version": "2025.04.01",
  "mcu": { ... },
  "network": [ ... ],
  "partitions": [ ... ]
}

Field	Type	Required	Description
uuid	string	Yes	Device UUID (RFC 4122 format)
product_id	string	Yes	Human-readable product identifier (e.g. FFC0806-2505)
product_hex	string	Yes	Hex product identifier (e.g. 0x08062505)
device_class	string	Yes	Device class (e.g. controller)
public_key	string	Yes	Base64-encoded uncompressed P-256 ECDSA public key (65 bytes, prefix 0x04)
registering_application	string	Yes	Name of the application performing registration
registering_version	string	Yes	Version of the registering application
mcu	object	Yes	MCU info (model, revision, cores, cpu_freq_mhz, idf_version, flash_chip_size, flash_chip_speed, flash_chip_mode, psram_size, features)
network	array	No	Network interfaces ([{ "interface": "wifi", "mac_address": "AA:BB:CC:DD:EE:FF" }])
partitions	array	No	Partition table entries

DynamoDB Record

The function writes the following item to the firefly-devices table:

Attribute	Description
uuid	Device UUID (partition key)
product_id	Human-readable product identifier
product_hex	Hex product identifier
device_class	Device class
public_key	Base64-encoded P-256 public key
registration_date	ISO-8601 timestamp of registration
registering_application	Name of the application that performed registration
registering_version	Version of the registering application
mcu	MCU information object
registered_by_email	Email of the user who generated the registration key
network	Network interfaces (if provided)
partitions	Partition table (if provided)

Response Codes

Code	Reason
204 No Content	Device registered successfully (or already registered)
400 Bad Request	Missing or invalid field, malformed UUID, invalid public key
401 Unauthorized	Missing, invalid, or expired X-Registration-Key
500 Internal Server Error	Unhandled exception

See the API Reference for full schema documentation.

Deployment

See the deployment workflow documentation for workflow steps, infrastructure dependencies, and failure scenarios.