API Overview

Base URL

http://localhost:3000     # development
https://your-domain.com   # production

Interactive docs are available at /swagger and the raw OpenAPI 3.1.0 schema at /doc.

Authentication

The backend (backend/) uses cookie-based JWT authentication issued by Crossmint. The cookie name is crossmint-jwt.

POST /api/auth/session
Content-Type: application/json

{
  "jwt": "<crossmint-jwt>",
  "refreshToken": "<optional-refresh-token>",
  "email": "user@example.com"
}

Rate Limits

The default rate limit is 30 requests per minute (RATE_LIMIT_RPM env var). Applied per authenticated user on all rate-limited routes — keyed on userId, not IP.

Error Format

All errors return a consistent JSON envelope:

{
  "error": "Human-readable description",
  "code": "MACHINE_READABLE_CODE"
}

Common Error Codes

Public Endpoints

These routes require no authentication:

CORS

The server allows credentials-bearing cross-origin requests from the following origins:

• http://localhost:8080
• http://localhost:3000
• http://localhost:3001
• http://localhost:5173
• "null" (file:// origin for local test pages)

The Access-Control-Allow-Origin header echoes the request origin exactly (never wildcard) when credentials are included.

Endpoint Summary