| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
For an overview of this process, please first go over the Registration page in the Quickstart guide, and the Authentication Overview section.
Request Data
| Name | Type | Required | Description |
|---|---|---|---|
| mac | string | See description | MAC address (optional unless authentication method is MAC&SN). Required for mac&sn authentication method |
| sn | string | Yes | Serial number - Has to be unique for devices from the same model |
| cloud_id | String | See description | GUID for the device prepended with a short code assigned to each manufacturer. More details here. Required for cloud_id authentication method |
| firmware_version | string | Yes | The current version of the firmware on the device. served as the base version for the device. |
| hardware_key | string | Yes | Unique key for each batch of manufactured devices.for each model. |
| name | string | Default friendly name for the device (can be changed later in the UI of the organization) | |
| details | object | Object containing any custom internal device details. | |
| sub_model | string | Sub-model name for differentiating similar devices. More details here. | |
| parent_id | uuid | UUID of a registered parent device for Application Devices. | |
| host_address | string | IP/Hostname of the device. | |
| nonce | string | See description | Challenge returned by the previous unsigned request. Required for x509 authentication method |
| signature | string | See description | Base64 of the nonce signed with the device private key (SHA-384). Required for x509 authentication method |
| x509_crt | string | See description | The device certificate, PEM encoded. Required for x509 authentication method |
| x509_chain | array | Intermediate certificates between x509_crt and your root CA, PEM encoded. Up to 4. |
Request Sample
{
"hardware_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"cloud_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"mac": "11:22:33:44:55:66",
"sn": "112",
"firmware_version": "1.0.1",
"name": "test device"
}Return Data
| Name | Type | Description |
|---|---|---|
| id | string | Unique ID for this device. Must be saved and used for all future API access |
| access_key | string | Unique access key for this device. Must be saved and used for all future API access |
| hub_url | string | URL of the hub server assigned to this device. |
| hub_url_static_cert | string | URL of the hub server assigned to this device that supports custom SSL certificates |
| mqtt_hub_url | string | For MQTT based devices. |
Registering again with an existing identity
A registration whose identity — cloud_id, or mac and sn, depending on the Model's
authentication method — matches an existing Device is
answered in one of three ways:
- Recreated (
201). The existing Device is unclaimed, unlicensed, has no child devices and has
not been seen for 24 hours (or, if it never reported, was registered more than 24 hours ago). It is
deleted and a new Device is created, and the response is the standard201above with a new
idandaccess_key. Persist both; the old credentials stop working. - Refused (
422). In every other case the server returns 422 — Device already registered.
If the existing Device is claimed by an Organization, a re-registration alert (an Approval required badge on the
Device, plus a "Device is trying to re-register" incident) is raised on it and
an admin can approve a replacement, which keeps the Device'sid(see Replace Device). Child devices and
unclaimed Devices are refused without an alert. An unclaimed Device that is still refused is
recreated once it has gone unseen for 24 hours; if it is licensed or has child devices, delete it
with Delete Device or contact Xyte support. - Blocked (
429). After a422Device already registered answer, or after a recreate,
repeat attempts with the same identity on the same Device Model get429 Too Many RequestswithRetry-After: 600for
10 minutes. After a422, approving the replacement or dismissing the re-registration alert on the
Device lifts the block at once; closing the incident alone does not. Child devices are never blocked; they keep getting422.
HTTP/1.1 429 Too Many Requests
Retry-After: 600
{ "error": "Too many requests" }The Device should wait at least the Retry-After interval before registering again.
Registering with an X.509 certificate
Device Models whose authentication method is X.509
Certificate register against this same endpoint in two steps. The Device proves it holds
the private key belonging to a certificate issued by your Certificate Authority.
Step 1 — register as usual
Send the registration request without nonce, signature and x509_crt:
{
"hardware_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"cloud_id": "ABCDxxxxxxxxxxxxxxxx",
"sn": "112",
"firmware_version": "1.0.1"
}The server answers 401 with a single-use challenge, valid for 120 seconds:
WWW-Authenticate: Xyte-X509 nonce="<nonce>", alg="ES384", max-age=120
{
"error": "certificate_required",
"nonce": "<nonce>",
"alg": "ES384",
"expires_in": 120
}No Device is created by this call.
Step 2 — sign the challenge and resend
Sign the nonce with the Device private key using SHA-384 and Base64 the result:
printf '%s' "<nonce>" | openssl dgst -sha384 -sign device.key | openssl base64 -AResend the same body, adding the challenge, the signature and the certificate:
{
"hardware_key": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"cloud_id": "ABCDxxxxxxxxxxxxxxxx",
"sn": "112",
"firmware_version": "1.0.1",
"nonce": "<nonce>",
"signature": "<base64 signature>",
"x509_crt": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
"x509_chain": []
}The server verifies that the certificate chains to a CA registered for the Device Model, that it
is within its validity period, that its Subject Common Name is the Device's cloud_id, and that
the signature was produced by the matching private key. On success it returns the standard 201
response documented above.
Everything after registration is unchanged: the Device authenticates with the returned
access_key, exactly like any other Device. The certificate is not presented again — keep it
on the Device, but holding it does not authorize a second registration. A unit that comes back
after a factory reset gets a challenge as usual, and it is the signed retry that is refused: while
the Device still exists, registering again under the same cloud_id returns 422 — Device
already registered. Unlike the 403s below, that response carries no error_code. While the
identity is blocked (see Registering again with an existing identity),
the unsigned first request itself is answered 429 with Retry-After: 600 and no challenge is issued.
An unclaimed unit that has gone unseen for 24 hours comes back on its own: the signed retry
recreates the Device (see Registering again with an existing identity).
Otherwise there are two ways to bring such a unit back, both resolved through this same endpoint. Deleting
the Device releases its cloud_id, after which a fresh registration succeeds as if the unit were
new — at the cost of the Device's history and the End Customer's claim. To keep both, an operator
stages a Device replacement against the existing Cloud ID; the next registration under that Cloud
ID is then accepted and re-issues the access_key. See
Replace Device.
Errors
Failures carry a stable error_code so firmware can tell a retryable challenge from a
provisioning fault.
| Status | error_code | Meaning | What the Device should do |
|---|---|---|---|
| 401 | certificate_required | A challenge was issued — also returned when the nonce sent was expired or already used | Sign the nonce just received and resend |
| 403 | certificate_untrusted | The certificate does not chain to a CA registered for the Model | Do not retry — provisioning fault |
| 403 | certificate_expired | The certificate is outside its validity period | Do not retry — provisioning fault |
| 403 | certificate_identity_mismatch | The Subject CN is not the cloud_id in the request | Do not retry — provisioning fault |
| 403 | certificate_already_registered | The certificate is already bound to another Device | Do not retry — provisioning fault |
| 403 | signature_invalid | The signature does not verify against the certificate | Do not retry — firmware or key fault |
| 403 | certificate_invalid | x509_crt or x509_chain could not be parsed | Do not retry — provisioning fault |
| 429 | — | Registration retry block: answered before any challenge | Wait Retry-After seconds, then start again |
A stale or already-used nonce is answered with a fresh challenge rather than an error, sothe Device's retry is always "sign the nonce you were just given".
