Device Registration

Before an Edge appliance can send telemetry or receive commands, it must register with the Cloud Backend. Registration is a one-time operation per device that produces a device_key used for all subsequent communication.

Registration flow

sequenceDiagram
    participant Operator
    participant CloudSPA as Cloud SPA
    participant CloudAPI as Cloud Backend
    participant Edge as Edge Appliance
    participant SQL as Azure SQL

    Operator->>CloudSPA: Create provisioning key (Settings → Edge Registration Keys)
    CloudSPA->>CloudAPI: POST /api/v1/edge/keys (JWT auth)
    CloudAPI->>SQL: INSERT edge_provisioning_keys (tenant_id, key, label)
    CloudAPI-->>CloudSPA: { key: provisioning_key }
    Operator->>Edge: Configure appliance with provisioning key

    Edge->>CloudAPI: POST /api/v1/devices/register (X-Provisioning-Key)
    Note right of Edge: body: { name: "edge-001", ... }
    CloudAPI->>SQL: Validate provisioning key (tenant_id)
    CloudAPI->>SQL: INSERT devices (tenant_id, name, device_key)
    CloudAPI-->>Edge: { device_id, device_key }
    Note over Edge: Store device_key securely. Provisioning key no longer needed.

Registration request

POST /api/v1/devices/register
X-Provisioning-Key: <provisioning_key>
Content-Type: application/json

{
  "name": "edge-plant-01",
  "location": "Building A, Floor 2",
  "type": "network-sensor"
}

Registration response

{
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_key": "dvc_a1b2c3d4e5f6...",
  "tenant_id": "..."
}

The device_key is a long random string generated at registration time. It is stored hashed in the database (not recoverable). The Edge appliance must store it securely on first receipt.

After registration

The Edge appliance uses device_key:

• As X-Device-Key header for all Ingestor uploads (POST /v1/ingest)
• For command polling (GET /api/v1/commands) — authentication mechanism TBD per implementation

Provisioning key management

Provisioning keys are created and managed by tenant administrators in Settings → Edge Registration Keys in the Cloud SPA. Key properties:

• Scoped to a tenant (devices registered with a key inherit the tenant)
• Can be labelled (e.g. “Plant A deployment batch”)
• Can be revoked (prevents future registrations, does not affect already-registered devices)

Database tables

Table	Migration	Content
edge_provisioning_keys	V21/V22	Per-tenant provisioning keys, labels, revocation
devices	V22	Registered devices, device_key hash, tenant link

See Backend/db/migration/V22__edge_device_control.sql for the full schema.