Overview

The first step in communicating with the cloud is for the Device to register itself and obtain the authorization credentials needed for all future API calls.

The Device should send its registration request as soon as it has network connectivity. The exact fields to include depend on the authentication method — see Authentication Method for the required fields per method.

Registration is performed via the Register Device API and returns the following fields:

• id — Unique ID assigned to the Device.
• access_key — Authentication key that must be used for all future communication.
• hub_url — URL of the Hub Server assigned to this Device.
• hub_url_static_cert — URL of the Hub Server assigned to this Device that accepts custom SSL certificates.
• mqtt_hub_url — Relevant only for Devices authenticating with MQTT. See MQTT Endpoints.

All subsequent communication must be directed to the server in hub_url (or hub_url_static_cert) and authenticated with the returned id and access_key. Pass the id in the deviceId URL parameter and the access_key in the HTTP Authorization header.

A Device can register only once. The Provisioning Server prevents a Device with the same Cloud ID or MAC/SN combination from registering again.

The Provisioning Server address and custom SSL settings are available in the Provisioning Server area of the Partner Portal.

Registration flow

On first boot, or whenever it first connects to the network, the Device calls the Register Device API against the Provisioning Server.

If registration fails, retry on every subsequent boot or network reconnection until it succeeds. A retry interval of around 15 minutes works well in practice.

Deleted devices

If a Device is deleted from the cloud (via API or via support), all subsequent API calls made by that Device will return HTTP 401 Not authorized. The Device must re-register to obtain a new id, access_key, and hub_url.

Child device registration

The Xyte architecture lets Devices that cannot reach the cloud directly communicate through a parent Device.

The parent Device registers as a normal Xyte Device, then calls the Register Child Device API to register each of its children. See the Child Devices section for the full pattern.

Sub-models

Some Device Models share the same Commands, Telemetry, and Configuration but differ in naming or minor hardware specifics. The platform supports these via Sub-models: pass a sub-model field in the registration body to identify which variant the Device is.