API¶
The Tomoda backend exposes a single REST/JSON API under the /api/v1 prefix, plus a WebSocket endpoint under /ws. All endpoints are documented in OpenAPI form by swag annotations on the handler functions and served by Swagger UI in non-production environments.
Base URLs¶
| Environment | Base URL |
|---|---|
| Local | http://localhost:8080 |
| Dev | (per devops repo) |
| Production | (per devops repo) |
The API host is configured in cmd/server/main.go via the @host Swagger annotation (currently localhost:8080) and @BasePath (/api/v1).
Authentication¶
Two header-based schemes:
| Header | Scheme | Use |
|---|---|---|
Authorization: Bearer <jwt> |
JWT | User-facing requests (mobile + web clients) |
X-API-Key: <key> |
API key | Server-to-server integrations |
JWTs are issued by POST /api/v1/auth/login (and the OAuth, WebAuthn, OTP equivalents) and refreshed via POST /api/v1/auth/refresh. The bearer scheme is the default for everything user-driven; the X-API-Key scheme is reserved for third-party integrations and uses API keys managed under /api/v1/auth/api-keys.
What to read next¶
- Conventions — request shapes, error responses, pagination, dates
- Rate Limiting — public-facing limits per endpoint
- Swagger / OpenAPI — how docs are generated and how to add annotations
For the implementation side of authentication, rate limiting, and security, see the Security section.