Register Device

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

For an overview of this process, please first go over the Registration page in the Quickstart guide, and the Authentication Overview section.

Request Data

NameTypeRequiredDescription
macstringSee descriptionMAC address (optional unless authentication method is MAC&SN). Required for mac&sn authentication method
snstringYesSerial number - Has to be unique for devices from the same model
cloud_idStringSee descriptionGUID for the device prepended with a short code assigned to each manufacturer. More details here. Required for cloud_id authentication method
firmware_versionstringYesThe current version of the firmware on the device. served as the base version for the device.
hardware_keystringYesUnique key for each batch of manufactured devices.for each model.
namestringDefault friendly name for the device (can be changed later in the UI of the organization)
detailsobjectObject containing any custom internal device details.
sub_modelstringSub-model name for differentiating similar devices. More details here.
parent_iduuidUUID of a registered parent device for Application Devices.
host_addressstringIP/Hostname of the device.
noncestringSee descriptionChallenge returned by the previous unsigned request. Required for x509 authentication method
signaturestringSee descriptionBase64 of the nonce signed with the device private key (SHA-384). Required for x509 authentication method
x509_crtstringSee descriptionThe device certificate, PEM encoded. Required for x509 authentication method
x509_chainarrayIntermediate 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

NameTypeDescription
idstringUnique ID for this device. Must be saved and used for all future API access
access_keystringUnique access key for this device. Must be saved and used for all future API access
hub_urlstringURL of the hub server assigned to this device.
hub_url_static_certstringURL of the hub server assigned to this device that supports custom SSL certificates
mqtt_hub_urlstringFor 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 standard 201 above with a new
    id and access_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's id (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 a 422 Device already registered answer, or after a recreate,
    repeat attempts with the same identity on the same Device Model get 429 Too Many Requests with Retry-After: 600 for
    10 minutes. After a 422, 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 getting 422.
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 -A

Resend 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.

Statuserror_codeMeaningWhat the Device should do
401certificate_requiredA challenge was issued — also returned when the nonce sent was expired or already usedSign the nonce just received and resend
403certificate_untrustedThe certificate does not chain to a CA registered for the ModelDo not retry — provisioning fault
403certificate_expiredThe certificate is outside its validity periodDo not retry — provisioning fault
403certificate_identity_mismatchThe Subject CN is not the cloud_id in the requestDo not retry — provisioning fault
403certificate_already_registeredThe certificate is already bound to another DeviceDo not retry — provisioning fault
403signature_invalidThe signature does not verify against the certificateDo not retry — firmware or key fault
403certificate_invalidx509_crt or x509_chain could not be parsedDo not retry — provisioning fault
429—Registration retry block: answered before any challengeWait Retry-After seconds, then start again

📘

A stale or already-used nonce is answered with a fresh challenge rather than an error, so

the Device's retry is always "sign the nonce you were just given".

Body Params
string

MAC address of the device

string
required

Unique device serial number

string

Unique device identifier (must specify this or mac)

string
required
Defaults to 1.0.0

Semver based firmware version

string
required

Key defined in the model's hardware key section

string

Display name for the end-user

string

Additional model details text

string

UUID of the parent device

Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json