API Reference
Complete list of REST endpoints and WebSocket messages.
User & Room Endpoints
Used by your mobile or web clients to authenticate users and interact with rooms.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/auth/auto | API key | Auto-create/find user and return session token |
| POST | /api/auth/token | client_id | Auth with client_id + username + password |
| POST | /api/token/refresh | None | Exchange refresh token for new access token |
| POST | /api/login | None | JSON login with username + password |
| POST | /api/register | None | JSON registration with username + password |
| POST | /api/logout | Bearer | Invalidate current session token |
| GET | /api/me | Bearer | Get current authenticated user info |
| GET | /api/channels | Bearer | List voice channels for current tenant |
| POST | /api/channels | Bearer | Create a new voice channel |
| GET | /ws | Bearer/token param | WebSocket signaling connection |
| GET | /health | None | Server health check |
Dashboard Endpoints
Used by the VoxaStream web dashboard. Authenticated via session cookie.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/auth/clerk-tenant | Clerk JWT | Exchange Clerk JWT for backend tenant session |
| GET | /api/tenant/me | Session cookie | Current tenant info |
| GET | /api/tenant/usage | Session cookie | Current month usage stats |
| GET | /api/tenant/rooms | Session cookie | List tenant rooms |
| GET | /api/tenant/users | Session cookie | List tenant users |
| GET | /api/tenant/api-keys | Session cookie | List API keys (masked) |
| POST | /api/tenant/api-keys | Session cookie | Create new API key |
| DELETE | /api/tenant/api-keys/revoke/{id} | Session cookie | Revoke API key |
| POST | /api/tenant/generate-token | Session cookie | Generate test user token |
| POST | /api/tenant/rooms/delete/{id} | Session cookie | Delete a room |
| POST | /api/tenant/logout | Session cookie | Invalidate tenant session |
WebSocket Messages
All messages are JSON objects with type and payload fields.
| Dir | Type | Description |
|---|---|---|
| → | join_channel | Join a voice channel. Payload: channel_id, role |
| → | leave_channel | Leave the current channel. |
| → | mute | Toggle mute state. Payload: muted (bool) |
| → | speaking | Voice activity. Payload: speaking (bool) |
| → | webrtc_offer | SDP offer for WebRTC negotiation. Payload: sdp |
| → | webrtc_answer | SDP answer. Payload: sdp |
| → | ice_candidate | ICE candidate. Payload: candidate (raw) |
| → | screen_preview | Screen share JPEG thumbnail. Payload: image (base64) |
| ← | channel_users | User list update. Payload: channel_id, users[] |
| ← | presence | All-channel presence update. |
| ← | webrtc_offer | Incoming SDP offer from SFU. |
| ← | webrtc_answer | Incoming SDP answer. |
| ← | ice_candidate | Incoming ICE candidate. |
| ← | screen_preview | Remote screen preview. |
| ← | screen_preview_clear | Screen share ended. |