API Reference

Registration

Overview

The first step in communicating with the cloud service is the device registering itself and obtaining the authorization keys needed for all future API calls.

The device should send the request for registration as soon as the device is connected to a network. The fields that should be sent are depending on the authentication method. More information about the required fields, based on the authentication method, can be found here.

The registration is performed via the Register Device API and results in the following keys being returned:

  • id - A unique ID assigned to the device
  • access_key - An authentication key that must be used for all future communication
  • hub_url - The URL of the hub server assigned for this device
  • hub_url_static_cert - The URL of the hub server assigned for this device that accepts custom SSL certificates
  • mqtt_hub_url - Relevant only for devices authenticating with MQTT. More details here.

All future device communication must be directed to the server identified by hub_url or hub_url_static_cert and use the id and access_key for authentication. The id should be used in the deviceId parameter of the URL, and the access_key should be used as the value of the HTTP Authorization header.

Each device can only be registered once. The provisioning server will prevent devices with the same Cloud ID or MAC/SN combination from registering again.

The address of the provisioning server and custom SSL information are available in the Provisioning Server area of the partners portal.

Registration flow

Upon initial boot, and when first connecting to the network, the device should use the Register Device API to register with the provisioning server.

In case of failure, it is recommended to continue trying to register on every boot or whenever the device connects to the network until successful (the suggested interval is 15 minutes).

Deleting devices

If a user or operator deletes a device from the cloud, via APIs or via support. All following API calls made by that device will immediately start returning a 401 status code with the message : "Not authorized" . The device will need to re-register and obtain a new id, access_key and hub_url.

Child device registration

The Xyte architecture allows devices that cannot communicate directly with the cloud to do so via a parent device.

The parent device should register as a regular Xyte device and use the Register Child Devices API to register each of its children. For more details, please use the Child Devices section.

Sub-models

There are some models that are sharing the same commands, telemetries, and configuration but have different naming or small differences between them. In order to support these types of products, we have been provided with the ability to define the sub-model of the registered device in order to differentiate very similar devices.
For that a sub-model field should be sent in the body of the device registration.