Device Lifecycle

A device is either active at one location or dormant. Each activation opens a location and an assignment. Deactivation closes that window. The same hardware can be activated again later.

---

Activation

Endpoint: POST /activate-device/

Query parameters: product_id, serial_number, and device_model (basic or pro). Requires a Bearer token.

Activation binds the device to the caller's organization and opens a place for telemetry.

• Creates the device record when the serial is new, and reuses it when the device is dormant.
• Creates a new active location.
• Creates a device assignment for that location.
• Writes the OEM organization_id, location_id, and token used by ingestion.

An already-active device is rejected. Deactivate it first.

---

Assignment to an application zone

Endpoint: PUT /locations/{location_id}/

Body: { "application_zone_id": "<zone uuid>" }. Pass organization_id as a query parameter.

Assign the location after it has coordinates inside the zone. Creating a zone can assign every unassigned device already inside the boundary. The map asks when you tap an unassigned device that sits in a zone.

• Sets application_zone_id on the first assignment only. That bind cannot be changed or cleared.
• Checks that the location and the zone belong to the same organization.
• Warns when the point is outside the zone. force_update overrides that spatial warning only. It cannot move a location that already has a zone.

To put the hardware in another zone, deactivate it, activate it again, and assign the new location.

---

Deactivation

Endpoint: POST /deactivate-device/

Query parameters: product_id and serial_number. Requires a Bearer token.

• Archives the active location.
• Closes the assignment.
• Marks the device dormant.
• Silences alerts for that location.
• Clears the OEM location_id and keeps the organization link so the device can be activated again.