Register New Devices

POST 
/v2/org/:org_id/devices

Register one or more devices to your organization.

Required Scope: write-devices

Overview

This endpoint supports bulk device registration with specified encryption mode, and custom naming and tagging.

Device Encryption Modes

Set Key Length

Set encryption key length to match your device firmware's encryption library requirement:

• 256-bit key (32 bytes): set encryption to "AES-256-CTR"
• 128-bit key (16 bytes): set encryption to "AES-128-CTR"
• 128-bit key, IN100 protocol (16 bytes): set encryption to "AES-128-EAX"

Set Counter Source for EID Rotation

The Hubble Device SDK rotates through ephemeral IDs (EID) so that devices are anonymous on the network. Specify the counter_source based on your hardware capabilities:

• Use "UNIX_TIME" for time-based encryption, e.g. for devices with a real time clock (RTC). This is the default value.
• Use "DEVICE_UPTIME" for timeless encryption, e.g. using the device uptime counter to rotate EIDs.

Set EID Rotation Period (AES-128-EAX only)

For the IN100 protocol (encryption of "AES-128-EAX"), you may optionally override the EID rotation period with eid_rotation.period_exponent: the base-2 exponent of the rotation period in seconds (matches the IN100 configuration field). Must be between 10 and 15 inclusive. The period defaults to period_exponent: 15, corresponding to 32,768 seconds (~9 hours).

Device Metadata

You can optionally provide names and tags for each device being provisioned:

• names: An array of device names.
• tags: An array of device tags.

Device Key

By default device.key is returned encoded in standard Base64 format, and is automatically compatible with the Hubble Device SDK. Pass key_format=hex to receive device.key as a lowercase hexadecimal string instead.

Atomicity

From the caller's perspective, this endpoint is all-or-nothing: a response is either a 200 listing every device you requested, or an error. There is no partial-success response — you will never receive a 200 containing some devices with keys and an error for the rest.

This does not guarantee that no devices were provisioned when you receive a 500 — see the 500 response below.

Request

Responses

200

Devices provisioned

400

Bad Request

413

Request Entity Too Large

500

Internal Server Error. Depending on where the failure occurred, some or all of the requested devices may still have been provisioned even though this response contains no key values.

Since you never received their keys, these devices are not usable and are not billed. You can find and remove them (e.g. by the tags or names you requested them with) with DELETE /v2/org/{org_id}/devices/{device_id}.