API Overview

Base URL

All API endpoints are served under:

http://localhost:8080/api/v1

The api/v1 prefix is versioned — future breaking changes will increment the version.

Authentication

Most endpoints require authentication via a JWT Bearer token. The token is obtained from POST /auth/login or POST /auth/register.

Include the token in the Authorization header:

Authorization: Bearer <access_token>

Token validation is performed by internal/middleware/auth.go:25 (Authenticate). The middleware extracts the user_id and organization_id from the JWT claims and injects them into the request context.

Public endpoints (no auth required):

• POST /auth/register
• POST /auth/login
• POST /auth/refresh
• POST /auth/password-reset-request
• POST /auth/password-reset-confirm

All other endpoints require authentication.

Security headers are applied globally via internal/middleware/security.go:198 (SecurityHeadersMiddleware), including X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security, and Content-Security-Policy.

Common Response Format

Successful responses follow this structure:

{
  "success": true,
  "data": { ... },
  "message": "Operation completed"
}

List endpoints return paginated results:

{
  "total": 42,
  "page": 1,
  "page_size": 10,
  "has_next": true,
  "items": [ ... ]
}

Error Handling

Errors are returned with appropriate HTTP status codes and a consistent body:

{
  "success": false,
  "error": "Error description",
  "details": "Additional details (if available)"
}

Status Code	Meaning
200 OK	Request succeeded
201 Created	Resource created
400 Bad Request	Invalid request body or parameters
401 Unauthorized	Missing or invalid auth token
403 Forbidden	Insufficient permissions
404 Not Found	Resource not found
409 Conflict	Duplicate resource
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server-side failure
503 Service Unavailable	Downstream service (e.g. Prometheus) unhealthy

Rate Limiting

Rate limiting is implemented via a token-bucket algorithm in internal/middleware/security.go:14 (RateLimiter). It applies per-IP and globally.

Default limits:

Scope	Limit
Per IP (global)	100 requests/minute
Global	1000 requests/minute

Whitelisted IPs bypass rate limiting. Blacklisted IPs are always blocked.

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 2026-06-11T14:30:00Z

When the limit is exceeded, the API returns:

{
  "error": "Rate limit exceeded",
  "limit": 100,
  "window": "1 minute",
  "message": "Too many requests from your IP address"
}

CORS

CORS is configured via internal/middleware/security.go:219 (CORSMiddleware). Allowed origins, methods (GET, POST, PUT, DELETE, OPTIONS), and headers (Content-Type, Authorization, X-Requested-With) are configurable.

Request Size Limit

Request bodies are limited to 1 MB by default (internal/middleware/security.go:250). Larger requests receive 413 Request Entity Too Large.