Onboarding

Onboarding is the first thing a device does: it registers with the platform and receives a client identity it uses from then on.

Who this is for: OT engineers connecting devices.

Authentication: RFC 9421 signatures

Margo devices authenticate using HTTP Message Signatures (RFC 9421) — each request is signed with the device’s key. There is no mutual TLS (mTLS) requirement.

In non-production or test setups, signature verification can be turned off at the gateway (a security toggle), but production deployments keep it on.

The onboarding request

The device sends an onboarding request whose body contains exactly three fields:

{
  "apiVersion": "...",
  "kind": "...",
  "certificate": "..."
}

• apiVersion and kind identify the Margo resource.
• certificate carries the device’s certificate.

The response

On success the platform responds with 201 Created and a body containing the device’s assigned client identity:

{
  "clientId": "..."
}

The field is clientId (camelCase). The device stores this clientId and uses it — together with its signed requests — for all later communication.

A tenant accepts onboarding only while it is active. If the tenant in the URL does not exist, or is deleted, disabled, suspended or pending, the platform responds with 403 Forbidden and the Margo error body:

{
  "error": "Client rejected"
}

The same response applies to the Root CA download (GET /<tenant>/api/v1/onboarding/certificate). It does not tell which of these cases applies, so it does not reveal which tenants exist.

What happens next

Once onboarded, the device:

1. reports its capabilities, then
2. begins polling for its desired state and
3. reporting deployment status.

In the Devices module you’ll see a newly onboarded device appear as pending, then move to online once it checks in.