API Reference

Authentication Method

Overview

The Authentication Method defines how an End Customer proves ownership when claiming a Device. Several options are available, trading off security against user friction.


📘

The Authentication Method governs how the End Customer proves Device ownership during claiming. It is not the same as how the Device authenticates with the server (which is always done with the id and access_key returned by registration).

X.509 Certificate is the exception: it additionally governs how the Device proves its own identity to the cloud at registration. Claiming still uses the Device's Cloud ID.


Authentication Methods

When you create a new Device Model in the Partner Portal, you select the Authentication Method. The Device firmware then implements the matching registration flow.

The options:

  1. MAC & Serial Number — uses the Device's MAC address plus serial number.
  2. Cloud ID (recommended) — uses a globally unique string per Device. See Generating a Cloud ID.
  3. Public Key — coming soon.
  4. X.509 Certificate — the Device proves its identity with a certificate issued by your own Certificate Authority. See X.509 Certificate below.

Every registration request must include the fields required by the chosen Authentication Method. Examples below.

Mac & Serial number

{
    "hardware_key": "",
    "mac": "",
    "sn": "",
    "firmware_version": "",
}

Cloud ID

{
    "hardware_key": "",
    "cloud_id": "",
    "sn": "",
    "firmware_version": "",
}

X.509 Certificate

{
    "hardware_key": "",
    "cloud_id": "",
    "sn": "",
    "firmware_version": "",
    "nonce": "",
    "signature": "",
    "x509_crt": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n",
    "x509_chain": []
}

With this method the Device holds an X.509 private key and certificate provisioned during
manufacturing, and registration is a two-step request — see Registering with an X.509 certificate
for the full flow and error codes.

You keep your own PKI: Xyte stores only your CA public certificate and never holds private
key material. To enable the method for a Device Model, send your CA certificate to Xyte and we
register it against that Model — Devices whose certificate does not chain to it are rejected.

Requirements:

  • The certificate's Subject Common Name (CN) must be the Device's Cloud ID. This is the
    identifier the cloud uses to recognise the Device, and the one printed on the box for claiming.
  • Sign the challenge with SHA-384. ECDSA on secp384r1 (ES384) is what the challenge
    advertises and what we recommend; RSA keys signing with SHA-384 also verify.
  • Certificates may be long-lived. The certificate is verified once, at registration, so no
    renewal service is required.
  • Each certificate may register exactly one Device.

For a complete worked example — minting a test CA, signing the challenge and registering a
Device with curl — see X.509 Registration Walkthrough.


🚧

Bulk registration is not available for X.509 Device Models

Each Device signs its own challenge with a key that never leaves the Device. Register Devices individually.


📘

Child Devices of an X.509 Device Model

Do not need their owncertificate; they are authorized by their parent.


The server response includes the Device's id and access_key. Every subsequent API call from the registered Device must put the access_key in the HTTP Authorization header and the id in the URL deviceId parameter:

curl --location --request POST 'https://hub.xyte.io/v1/devices/{device_id}/telemetry' \
--header 'Content-Type: application/json' \
--header 'Authorization: xxx-xx...' \

Updated 7 days ago

Updated 7 days ago