Device Registration

Edge appliances register with the Cloud Backend using a claim code flow. The legacy registration-key model (POST /devices/register, Settings → Edge registration keys, edgezu-tui) has been removed from Backend and Edge.

Note: Cloud SPA may still contain a dead Settings page for registration keys — Backend returns 404. Do not use it.

Roles

Actor	Action
Technician on device	Runs `monozu edge register` — displays claim code
Staff / automation	Calls Cloud internal assign API (Management UI for this is not shipped yet — see `TODO.md`)
Customer in Cloud SPA	Views devices; may edit label/location — does not assign claims

Path prefix note

Layer	Device control paths
Backend (Fiber)	Mounted under `/api/v1` (e.g. `/api/v1/devices/announce`)
Edge client (`edgezu-common`)	Calls `/v1/...` on the cloud base URL (e.g. `/v1/devices/announce`)

Production may rewrite /v1 → /api/v1. When documenting Backend handlers, use /api/v1. When documenting Edge client calls, use /v1 as in Edge source.

Default Edge cloud URL: https://api.cloud.monozu.io (Edge/crates/edgezu-common/src/endpoints.rs). Internal Docs historically also listed api-cloud.monozu.io — treat hostname as env-specific until DNS is unified (TODO.md).

Registration flow

sequenceDiagram
    participant Tech as Technician
    participant CLI as monozu edge register
    participant API as Cloud Backend
    participant Staff as Staff or M2M
    participant SQL as Azure SQL

    Tech->>CLI: Run on appliance
    CLI->>API: POST /v1/devices/announce
    API->>SQL: INSERT device_claims pending
    API-->>CLI: claim_code, claim_token, expires_at
    CLI->>Tech: Display XXX-XXX code
    loop Poll every ~5s
        CLI->>API: GET /v1/devices/claim-status
        API-->>CLI: pending or assigned or expired
    end
    Staff->>API: POST /internal/devices/assign
    Note right of Staff: Bearer CLOUD_INTERNAL_API_TOKEN
    API->>SQL: CREATE device, claim assigned
    CLI->>API: GET /v1/devices/claim-status
    API-->>CLI: assigned
    CLI->>API: POST /v1/devices/claim-complete CSR
    API->>SQL: Mint api_key, claim consumed
    API-->>CLI: device_id, api_key, certs

Device-facing API (Edge client paths)

Base URL: Cloud API. Handlers: Backend/internal/domain/devices/.

Endpoint (Edge client)	Backend mount	Auth	Purpose
`POST /v1/devices/announce`	`/api/v1/devices/announce`	None (rate limit per IP)	Create/reuse pending claim
`GET /v1/devices/claim-status`	`/api/v1/devices/claim-status`	Bearer `claim_token`	`pending` / `assigned` / `expired`
`POST /v1/devices/claim-complete`	`/api/v1/devices/claim-complete`	Bearer `claim_token`	CSR → `api_key` + optional mTLS cert

Announce

hw_serial from /proc/cpuinfo or MAC fallback.
Same IP re-announce: reuse claim / rekey token.
Different IP for same serial: rejected.

Claim-complete

Only when status is assigned.
Optional mTLS client cert from Devices CA — PKI runbook.

Assign API (Cloud internal — for Management)

Auth: Authorization: Bearer <CLOUD_INTERNAL_API_TOKEN>.

Endpoint	Purpose
`GET /internal/device-claims`	Pending claims (serial, time, IP — no claim code)
`POST /internal/devices/assign`	Body: `claim_code`, `tenant_id`, optional `name`, `location`

Source: Backend/internal/app/register_internal.go, internal/domain/internalapi/devices.go.

Management Frontend does not yet expose Assign UI — operators need M2M/curl or a future Management page (TODO.md).

Tenant fleet (customer SPA)

Endpoint	Purpose
`GET /api/v1/edge/devices`	Tenant device list
`PATCH /api/v1/edge/devices/{id}`	Update `label` / `location`

Resume state

/data/edgezu/claim.json (mode 0600). Re-run monozu edge register continues; --new forces fresh announce.

After registration

Ingestor: X-Device-Key = api_key on POST /v1/ingest
Commands: long-poll updates last_seen_at
Online: last_seen_at within 90 seconds

Database

Table	Migration	Content
`device_claims`	V50	Claim lifecycle
`devices` / edge device rows	V22+	Tenant-owned devices; `hw_serial`, `location`, `label`

Legacy edge_registration_keys may still exist in DB but is unused.

Failure modes

Symptom	Check
Claim expired (~24h)	Re-run `monozu edge register`
announce rate limited	Per-IP middleware
stuck pending	Assign not called (`POST /internal/devices/assign`)
claim-complete fails	Claim not `assigned`

Historical (removed)

POST /api/v1/devices/register with registration key
Backend Settings Edge registration keys API
edgezu-tui