API Overview

Base URL

All API endpoints are prefixed with /api/ and served by the Hono Worker.

• Local: http://localhost:8787/api/ (proxied from Vite at :5173)
• Production: https://app.dotcollective.com.au/api/

Middleware Chain

Every API request passes through:

1. Auth middleware - Validates CF Access JWT, upserts user, sets c.set("user", user)
2. Permission middleware (per-route) - Checks tool-level permissions for the action
3. Route handler - Processes request with scoped data access

Response Format

// Success
{ "data": { ... } }

// Error
{ "error": "Human-readable error message" }

Authentication

All endpoints require a valid Cloudflare Access session. The JWT is automatically included by the browser’s CF Access session cookie.

For local development, use the CF-Access-Mock-Email header:

curl -H "CF-Access-Mock-Email: brendon@dotcollective.com.au" \
  http://localhost:8787/api/users/me

Data Scoping

Route handlers scope queries based on the authenticated user’s access level:

• Executive / Head: All records
• Manager: Own records + records from squad members
• Lead / Employee: Own records only