Device Management (Registry)

:::info Status Implemented. Source: docs/device-management-module-architecture.md §7; fastapi-backend/api/v1/endpoints/device_registry.py, fastapi-backend/core/device_registry.py, fastapi-backend/core/device_claim.py, fastapi-backend/core/inventory_registry.py, fastapi-backend/core/device_transfer.py. :::

The device registry is the unified authorization spine for both sold device kinds (transmitter, stream player) — inventory tracking, the approval lifecycle, mosque binding moves, ownership transfer, and warranty replacement, all in one place. Concepts behind this module: Identity, Ownership, Device Authorization, Mosque Binding, Device Lifecycle.

Mounted at /api/v1/device-registry, distinct from the older /api/v1/devices and /api/v1/mosque-devices routers (kept as separate routers deliberately — sharing a path prefix would make routing depend on registration order in api/v1/api.py).

Super Admin work queue

Everything that moves lifecycle_status is Super Admin only, except the two entry points that are asymmetric by design:

Method	Path	Auth	Purpose
POST	/device-registry/announce	none (IP rate-limited)	Unprovisioned unit self-announces. Creates a PENDING row only if the serial/MAC matches a manifested inventory row; otherwise logged to unmanifested_announcements. No credentials ever returned
POST	/device-registry/claim	user JWT	The buyer claims a sold unit — cross-checked against inventory (see Identity), opens ownership + assignment, releases broker credentials, stays PENDING
GET	/device-registry/devices	superadmin	Paginated registry, filterable by status/kind/mosque/owner/connectivity
GET	/device-registry/devices/{id}	superadmin	Identity, bindings, config, health rollup
POST	/device-registry/devices/{id}/transitions/{action}	superadmin	The lifecycle transition matrix, one cell per call
POST	/device-registry/devices/{id}/approve	superadmin	verify + activate in one transaction — the common path for an already-sold, already-bound unit
POST	/device-registry/devices/{id}/transfer-ownership	superadmin	See Ownership
POST	/device-registry/devices/{id}/replace	superadmin	Warranty replacement — see Ownership
GET	/device-registry/devices/{id}/assignments · /audit · /events	superadmin	Binding history · audit trail · telemetry events
POST	/device-registry/devices/{id}/cmd	superadmin	Send a device command
GET	/device-registry/announcements	superadmin	The queue of units matching no manifest
POST	/device-registry/announcements/{id}/promote	superadmin	Explicit, audited import of an unmanifested announcement into inventory
GET/POST/PATCH	/device-registry/inventory, /inventory/{id}	superadmin	Procurement records
POST	/device-registry/inventory/import	superadmin	Batch import (CSV/JSON)
POST	/device-registry/inventory/{id}/transitions/{action}	superadmin	The inventory asset's own state matrix — see Device Lifecycle
POST	/device-registry/inventory/{id}/claim	superadmin	Bind an inventory row to a device manually

Full request/response schemas: API Reference.

The biggest operational risk — approval-queue cutover

:::danger Rollout risk Every existing self-registered stream player (legacy user_devices receiver rows) was approved by nobody. At cutover, all of these devices enter the Super Admin approval queue and stop streaming until approved. :::

Per docs/device-management-architecture-summary.md: no authorization flip while any existing customer receiver remains unapproved — the rollout plan must gate the stream-authorization flip on this queue reaching zero, with affected devices tracked by serial number. This is the same STREAM_AUTHZ_ENFORCE flag documented operationally in Backend Deployment — that page covers the mechanical flip; this callout is the business risk driving why it isn't flipped yet.

Owner-facing (no Super Admin gate)

See Mosque Binding — owner-facing API for /my-devices/* — rebinding is deliberately not superadmin-gated.

Related roadmap

The registry described here unifies what used to be split across mosque_devices (transmitters) and user_devices (stream players + app rows conflated together) — see Roadmap — Device Registry Unification for the migration sequencing.