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

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.