Skip to content

Gateway Enrollment & Provisioning

How a blank mini PC becomes a managed gateway, and how it gets its identity. The sequence is drawn in How It Works.

Identity

A gateway's identity is the server-minted gateway_id (gw- followed by 8 hex characters) and api_token. Both are stored in the agent's identity.json (mode 0600).

  • Nexus stores only the SHA-256 of the token. It finds a device by hashing the presented Authorization: Bearer token.
  • The MAC address is recorded as information, never as identity, so the number of NICs does not matter.

Bootstrap tokens

Gateways enrol with an enrollment_codes row of type='bootstrap', created by a platform admin in Admin > Enrollment (PortalAdminService.CreateBootstrapToken). A token is:

  • not MAC-locked: one token can enrol many devices;
  • use-capped when max_uses is set (max_uses=1 makes it single-use);
  • revocable (revoked_at) and optionally expiring (expires_at);
  • named, for a batch or an installer.

A leaked token can only put devices into the holding zone, and it can be revoked.

Enrolling

The agent enrols with:

edge-agent setup --addr https://<nexus> --realtime wss://<realtime> --token <bootstrap token>

Run without flags, setup starts an interactive wizard. The provisioning USB runs the same command on first boot. See Provisioning.

GatewayEnrollmentService.Enroll checks that the token is not revoked, not expired and under its use cap. It then creates the device and returns gateway_id and api_token in plaintext, once.

Holding zone and status

Every enrolment lands in the holding zone: status='holding' and org_id IS NULL. enrolled_via records which token was used.

Status Meaning
prepared A logical device created ahead of its hardware (CreateDevice / CloneDevice)
holding Enrolled, belongs to no organization
assigned Belongs to an organization (AssignGateway)
retired / revoked Out of service

Assigning a device out of the holding zone requires a platform admin, or SUPPORT_ADMIN (system action device:manage).

Only assigned devices receive agent updates (OTA).

Moving between environments

PortalGatewayService.Reenroll takes the target nexus and realtime URLs, plus a one-time token minted in the target environment's portal, and pushes them to the device as a reenroll command. The agent enrols there before it drops its current identity, so a failed move leaves a device that is still reachable. The OTA signing key is shared across environments, so a moved device keeps trusting releases. See Moving between environments.