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
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. When the key expires, repeat the claim-auth call.
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. This updates last_seen and keeps the device marked as active in the dashboard.