kooltab-backoffice/docs/api.md

API Documentation

Base URL: http://localhost:3001/api/v1

Swagger UI: http://localhost:3001/api/docs

Authentication

Dashboard Users

• Login to receive JWT access token (24h) + refresh token (30 days)
• Include access token in Authorization: Bearer <token> header

Devices

• Register to receive device bearer token (90 days)
• Include device token in Authorization: Bearer <token> header
• Device ID must match URL parameter

Endpoints

Health

GET /health - Server health check

Auth

POST /auth/login - Login with email/password POST /auth/refresh - Refresh access token POST /auth/logout - Logout and revoke refresh token

Venues

GET /venues - List venues GET /venues/:venueId - Get venue details GET /venues/:venueId/devices - List devices in venue

Devices

POST /devices/register - Register a new device POST /devices/:deviceId/sync - Sync device state (device auth) POST /devices/:deviceId/commands/:commandId/ack - Acknowledge command (device auth) GET /devices/generation-code - Generate registration code (admin)

Tabs

GET /venues/:venueId/tabs - List open tabs

Commands

POST /venues/:venueId/commands - Create a command GET /venues/:venueId/commands - List command history POST /venues/:venueId/devices/:deviceId/revoke - Revoke device (admin)

Error Format

{
  "error": {
    "code": "error_code",
    "message": "Human-readable message"
  }
}

HTTP Status Codes

• 200 Success
• 201 Created
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 409 Conflict
• 429 Too Many Requests