Device Registration

This page shows the complete onboarding flow for an Edge appliance — from generating a provisioning key in the Cloud SPA to the device being ready to send telemetry.

End-to-end flow

sequenceDiagram
    participant Operator as Operator (SPA)
    participant CloudSPA as Cloud SPA
    participant CloudAPI as Cloud Backend
    participant DB as Azure SQL
    participant Edge as Edge Appliance
    participant Ingestor as Ingestor Service

    Note over Operator,CloudSPA: Step 1: Create provisioning key
    Operator->>CloudSPA: Navigate to Settings → Edge Registration Keys
    CloudSPA->>CloudAPI: POST /api/v1/edge/keys { label: "Plant A" }
    CloudAPI->>DB: INSERT edge_provisioning_keys (tenant_id, key, label)
    CloudAPI-->>CloudSPA: { provisioning_key: "prov_abc..." }
    Operator->>Operator: Copy provisioning key

    Note over Operator,Edge: Step 2: Configure Edge appliance
    Operator->>Edge: SSH into appliance
    Operator->>Edge: Set CLOUD_API_URL and PROVISIONING_KEY in edge config
    Edge->>Edge: edge-agent starts

    Note over Edge,CloudAPI: Step 3: Device registration (automatic)
    Edge->>CloudAPI: POST /api/v1/devices/register (X-Provisioning-Key)
    Note right of Edge: body: { name: "edge-plant-a-01" }
    CloudAPI->>DB: Validate provisioning key (tenant_id resolution)
    CloudAPI->>DB: INSERT devices (tenant_id, name, device_key=hash(generated))
    CloudAPI-->>Edge: { device_id, device_key }
    Edge->>Edge: Store device_key securely (keyring or encrypted file)

    Note over Edge,CloudAPI: Step 4: Ongoing operation
    loop Command polling (every N seconds)
        Edge->>CloudAPI: GET /api/v1/commands (X-Device-Key)
        CloudAPI-->>Edge: [] (or commands if any)
    end

    loop Telemetry upload (every N seconds)
        Edge->>Ingestor: POST /v1/ingest (X-Device-Key)
        Note right of Edge: body: [{ kind: "telemetry", ... }]
        Ingestor->>DB: INSERT ingest_events
        Ingestor-->>Edge: 204 No Content
    end

Post-registration visibility

After registration, the device appears in:

• Cloud SPA → Assets — if auto-import is enabled, a new asset may be created from the device
• Cloud SPA → Settings → Edge Devices — device management list with status and last-seen timestamp

Operators can revoke a device’s key from the device management list, which immediately blocks further telemetry uploads and command polling for that device.

OTA update trigger (optional)

If a new snap version is available, the command polling response includes an update_snap command:

sequenceDiagram
    participant Edge
    participant CloudAPI as Cloud Backend
    participant Blob as Azure Blob Storage

    Edge->>CloudAPI: GET /api/v1/commands
    CloudAPI-->>Edge: [{ command: "update_snap", payload: { version: "1.2.3" } }]
    Edge->>CloudAPI: GET /api/v1/snaps/latest
    CloudAPI-->>Edge: { version: "1.2.3", download_url: "https://..." }
    Edge->>Blob: GET download_url (snap blob)
    Edge->>Edge: Verify SHA256 checksum
    Edge->>Edge: Apply snap update (snapd)
    Edge->>CloudAPI: POST /api/v1/commands/:id/ack { status: "completed" }

Security considerations

• The provisioning key is single-use per device registration (or rate-limited) — exposing it briefly during setup is acceptable, but it should be revoked after all devices in a batch are registered
• The device key is long-lived; store it in a protected keyring on the appliance
• All communication uses HTTPS in production
• The Ingestor validates the device key on every request and resolves tenant_id from it — cross-tenant data injection is not possible