API Key
All endpoints require authentication via the X-API-Key header, except GET /health.
curl -H "X-API-Key: YOUR_API_KEY" https://your-api-host/devices
Roles
| Role | Access |
|---|
| User | Devices, telemetry, commands, lock events, trips, and WebSocket — scoped to assigned devices |
| Admin | Everything above (unrestricted) plus device management, configuration, and user management |
Device Scoping
Non-admin users are restricted to specific devices using the allowed_hardware_ids field on their user record. This scoping applies to:
- REST API — all
/devices/:id/* routes, /lock-events, /trips
- WebSocket —
subscribe and command messages
allowed_hardware_ids value | Access |
|---|
Array of IDs (e.g. ["ABC123", "DEF456"]) | Can access only those devices |
null or undefined | No device access (must be explicitly set to an array) |
| (Admin users) | Unrestricted access to all devices |
Users with allowed_hardware_ids set to null have no device access. You must explicitly set it to an array for the user to access any devices.