Overview
A Device replacement lets a Device that is already registered register again without losing
its identity: its id, history, telemetry, configuration and the End Customer's claim all stay.
It covers a failed unit swapped for a new one of the same Model, and a unit that was factory reset
and lost its id and access_key.
Nothing changes on the Device side: firmware calls Register Device exactly as
on first boot. What changes is on the server — an operator has staged the replacement, so the
registration is accepted and the existing Device record is reused instead of being refused.
Why a second registration is refused
While a Device exists, registering again under the same identity — cloud_id, or mac and sn,
depending on the Model's authentication method — returns
422 — Device already registered, with no error_code:
{ "error": "Device already registered" }The server also flags the existing Device in the Organization portal with an Approval required
badge. The flag is stamped at most once per throttling interval, so there is nothing to gain from
registering in a tight loop: back off and keep retrying until the registration is accepted (see
Error handling).
Child devices cannot be replacedA Device registered under a parent (Application Devices) gets the same
422, but no flag is raised and no replacement can be staged for it.
How a replacement is staged
A replacement is a pending identifier stored on the existing Device record: the serial number
or Cloud ID the next registration is expected to present. An operator sets it in one of two ways.
In the Organization portal, Manage → Replace device on the existing Device, entering the new
unit's serial number or Cloud ID — whichever the Model authenticates by. The same action is
available to the partner from the Device attached to a support ticket. Portal procedure:
Replace a device in the customer docs.
The new unit must not already be registeredA replacement completes when the new unit registers. A unit that already holds valid
credentials never calls Register Device again, so the pending replacement will not trigger.
Delete that unit's own Device record first; when it registers afresh, the replacement picks it up.
After the 422 above, the administrator opens the flagged Device and clicks Approve. This
stages a replacement against the Device's own current identifier, so the same unit is accepted
when it registers next. Dismiss clears the request instead; the Device keeps being refused and
the badge comes back on its next attempt.
Staging a replacement immediately revokes the Device's licenses (they stay attached and re-activate
once it reconnects; platform licenses in use stay active), aborts its active commands and closes
its open incidents.
What happens on the next registration
On POST /v1/devices the server, before the uniqueness check, looks for a Device of the same
Model whose pending identifier matches the request — the pending serial number against sn, or the
pending Cloud ID against cloud_id. The match is exact and case-sensitive after trimming
surrounding whitespace. When it matches:
- The existing record takes the registering unit's
sn,mac,cloud_id,firmware_version,
sub_model,details,hardware_keyandhost_address(and its certificate, for X.509 Models),
and the pending identifier is cleared. - The
access_keyis regenerated; any credentials the old unit still holds stop working. For
MQTT based devices the broker authorization is refreshed as well. - The response is the standard
201of Register Device. Theidis the
same Device id as before — onlyaccess_keyis new. Persist it before use, as on a first
registration. replacement_initiatedandreplacement_completedevents are written to the Device's history.
The same handling applies to every entry of a Bulk Register Devices
request.
Replacement versus deleting the Device
Both let a unit register again; they differ in what survives.
| Replacement | Delete Device | |
|---|---|---|
Device id | Kept | New Device, new id |
| History, telemetry, configuration | Kept | Lost |
| End Customer's claim | Kept | Lost — the Device must be claimed again |
access_key | Re-issued | Issued for the new Device |
| What is freed | Nothing | The cloud_id (and the certificate, for X.509 Models): uniqueness is enforced among live Devices only, so a fresh registration succeeds as if the unit were new |
Delete when a unit changes owner. Replace when the unit, or its successor, should carry on as the
same Device.
X.509 Models
For Models whose authentication method is X.509 Certificate the two-step challenge described on
Register Device runs as usual; the replacement decision is made on the
signed retry.
A reset unit re-presents its own certificate. It is deliberately not refused with
certificate_already_registered — that check only fires when the certificate is bound to a Device
with a different cloud_id — so the signed retry reaches the replacement handling: 422 until a
replacement is staged, accepted once it is.
A swapped unit presents its own, different certificate. Its Subject Common Name must be the
cloud_id the operator entered as the replacement Cloud ID, it must chain to a CA registered for
the Model, and it must not already be bound to another Device. On success the Device record is
re-bound to the new certificate.
Firmware checklist
- Treat 422 — Device already registered as "wait for an operator": back off and keep retrying
registration at a sensible interval. - On
201, persist the returnedaccess_keybefore using it. Theidis unchanged after a
replacement, but always store what the response returns. - Never keep using credentials saved before a reset; they are revoked when the replacement completes.