What is a device?
A device is a physical ESP32-based recorder. Once paired with a user account, it can start/stop sessions and upload audio independently of the web app. Devices authenticate with a device-scoped API key rather than a user JWT.Pairing flow
Pairing links a physical device to a user account in two steps:- Device publishes a pairing code — generates a short token and displays a QR code
- User confirms pairing — scans the QR code in the web app, which calls the confirm endpoint
Endpoints (device side, no auth required)
Endpoints (user side, JWT required)
Pairing token rules
- Expires 15 minutes after creation
- One-time use — invalidated once pairing is confirmed
- Unique per device at any given time
Device API key
After the user confirms pairing (paired: true on the status poll), the device calls POST /api/devices/pair/claim-auth:
X-API-Key: {device_auth_token} on all protected calls. Keys last 30 days (devices.api_key_expiry_hours). Within that window the device can power-cycle and keep using the stored key — no new confirm. After expiry, pair again to mint a fresh key.
led_color is the ring colour (#RRGGBB, default #C8C8C8). Firmware also accepts led_colour. Including it here lets the device apply colour before the first heartbeat.
Protected device endpoints (API key required)
Heartbeat
Devices should callPOST /api/devices/{device_id}/heartbeat periodically (every ~30s) while online — including while recording, so stop commands can be delivered. This updates last_seen, stores live telemetry in Redis, and returns pending commands plus the current ring colour.
Heartbeat request (all fields except firmware_version are optional; older firmware may send only the version):
battery_mv and battery_pct are optional. Firmware omits them when the ADC reading is implausible (no cell, or the BAT_ADC jumper is unpopulated). The API stores only millivolts in 2800–4500 and percent in 0–100.
battery_charging and battery_remaining_s are optional. Remaining seconds are stored only when not charging and in 0–172800 (48 h). Charging clears remaining.
wifi_rssi is optional STA signal strength in dBm (−120…0). Omitted when the device is in AP mode or offline.
sd_total_mb, sd_used_mb, and sd_used_pct are optional. Firmware omits them when the card is unmounted or FAT usage cannot be read. The API stores megabytes in 0–4_000_000 and percent in 0–100.
GET /api/devices/{device_id} includes that telemetry as live until the heartbeat timeout elapses.
The 200 body includes queued commands and the current ring colour. There is no push channel: the device applies colour and commands on the next successful heartbeat.
led_color first, then led_colour. Both are the same canonical #RRGGBB string stored on the device row (devices.led_colour).
Remote commands
Owners queue commands withPOST /api/devices/{device_id}/commands (JWT). They sit in Redis until the next heartbeat (TTL 5 minutes). Known commands:
SSID max 32 characters; password max 64.
Ring colour
Owners pick the colour on the device settings page. The ring updates on the next heartbeat; no extra command channel is required.
Admin (platform operators)
Admin-only endpoints require a user JWT with theadmin role.
Use force-unpair when a MAC is stuck on another account or half-paired — then clear device NVS and pair once.
POST /api/devices/pair/claim-auth rotates keys for that device and does not consume the workspace max_keys_per_user quota. Leftover ESP32 … keys from deleted device rows are purged on claim.