Skip to main content

​
Authentication

All endpoints require authentication via the X-API-Key header, except /health. 
curl -H "X-API-Key: your-api-key" https://api.example.com/devices

​
Access Levels

LevelSymbolDescription
No Auth-Public endpoints (/health, /mcp)
User✓Standard API operations
Admin🔐Full access including user management

​
User Role

Users can access device data filtered by their allowed hardware IDs: 
# List devices (must provide hardware_ids)
curl -H "X-API-Key: your-user-key" \
  "https://api.example.com/devices?hardware_ids=ABC123&hardware_ids=DEF456"

# Get device details
curl -H "X-API-Key: your-user-key" \
  https://api.example.com/devices/ABC123

​
Admin Role

Admins have full access to all endpoints: 
# List ALL devices (no filter required)
curl -H "X-API-Key: your-admin-key" https://api.example.com/devices

# Get system stats
curl -H "X-API-Key: your-admin-key" https://api.example.com/stats

​
WebSocket Authentication

Pass the API key as a query parameter: 
wss://api.example.com/realtime?api_key=your-api-key
Or via X-API-Key header if your WebSocket client supports custom headers.
Unauthorized connections receive 401 Unauthorized and are closed immediately.

​
API Key Management

API keys are managed by admins via the Users API.
API keys are only shown once when created. Store them securely.