| 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 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 so it can re-register after a factory reset.
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 |
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".