Skip to main content

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:
  1. Device publishes a pairing code — generates a short token and displays a QR code
  2. User confirms pairing — scans the QR code in the web app, which calls the confirm endpoint
See the Device Pairing Flow diagram for the full sequence.

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:
Returns:
The device stores this token and sends it as 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)

A device API key is scoped to that device. Using device A’s key for a session started by device B will return 403 Forbidden.

Heartbeat

Devices should call POST /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.
Firmware reads 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 with POST /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 the admin 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.