A device must prove who it is before its data is accepted, and an organisation must prove it owns a device before it can add it. This page explains how Hermetry protects both steps, for licensed devices (with a factory identity) and for devices that register themselves with a provisioning key. The how-to is in Adding and claiming devices and Licensed devices.
Factory identity
Every licensed device leaves the factory with:
| Item | Protection |
|---|---|
| A serial number | 6 to 32 letters, digits and dashes. Reserved for the device: no organisation can create an MQTT login with the same name. |
| A key pair and a certificate | The private key is made on the device and never leaves it. The certificate comes from Hermetry’s CA. See The device certificate authority. |
| A claim secret | A 20-character code. Hermetry stores only a hash of serial and code; no page, API or export ever shows the code or its hash. |
There is no printed claim label. The claim QR and code are shown only on the device’s local panel, behind its login, so someone who sees the device on a shelf cannot claim it.
Before a device is claimed
An unclaimed device belongs to no organisation. It can reach Hermetry with its certificate, but its data is dropped.
First connection (bootstrap)
A device that has no certificate yet connects with its factory provisioning key and receives a one-time bootstrap password:
- 32 random characters, valid for 10 minutes, bound to the serial;
- usable by exactly one session: a second session with the same password is refused;
- consumed when the device has its certificate.
The device then sends its certificate request over the bootstrap session and continues with mutual TLS. Provisioning requests are rate-limited per serial and per key, and a key used unusually often alerts Hermetry’s operators.
Claiming
You claim a device with its serial and claim code (or the QR). Several checks protect the claim:
| Check | Why |
|---|---|
| Claim window | The device’s owner must press Open claim window on the device’s Cloud page. The window is opened only by the device itself over its own certificate session, and stays open for at most 15 minutes. A stolen serial and code are useless while the window is closed: “The claim window on the device is closed.” |
| Claim code | Compared in constant time. A wrong code is counted and written to the audit log. |
| Attempt limits | At most 5 failed claims per serial, 20 per person and 30 per address per hour: “Too many attempts for now. Wait an hour, then try again.” A dry run counts like a real claim. |
| Ownership | A device owned by another organisation cannot be claimed: “This device is owned by another account. Ask the seller (or previous owner) to release it in their account, then try again.” |
| Device limit | Checked before anything is created; if your plan’s limit cannot be read, the claim is refused. |
A successful claim, in one step, creates the device with its model’s profile, binds its certificate as the device’s credential, ends its pool session and lets it reconnect as your device within seconds. A claim that stops halfway is resolved automatically within minutes; meanwhile a new attempt answers “This device is being added right now.”
Claiming needs the Admin role (permission iot_provisioning.claim).
Release
To pass a device to another owner, release it on its Ownership tab (you type the serial to confirm). Release returns the device to the factory pool; the next owner must open a new claim window. A factory reset does not release a device.
A device can also release itself with the Release button on its own Cloud page. You then get the notice “A device released itself from your account”. If nobody in your team did this, someone has access to the device’s local panel: change its panel password and contact support.
Devices that register themselves
A device without a factory identity can register itself with a device profile’s provisioning key. Two strategies limit the risk of a leaked key:
| Strategy | Protection |
|---|---|
| Only pre-provisioned devices | The key only works for devices you created beforehand. |
| Allow creating new devices | New devices are created Quarantined: they can log in, but their data is dropped until an administrator activates them. They count toward your device limit, so a flood is visible. |
Rotate a provisioning key that may have leaked; the old key stops working. See Quarantine for self-registered devices and Device profiles.
What is audited
Claim windows opened and closed, claims, failed claim codes, releases (by you or by the device), quarantine activations, provisioning key changes and certificate events are all in the audit log. See What is audited.
Recommendations
- Keep the local panel password of licensed devices secret and change the default.
- Claim devices only from inside your organisation, and release them before you sell or return them.
- Keep self-registration on Only pre-provisioned devices where you can; otherwise keep quarantine on.
- Watch the audit log for repeated failed claims of your serials.