API Reference

Routes & Auth

Base URL#

Authentication#

Every request to the API must include a Clerk session token in the Authorization header:

Authorization: Bearer <clerk-session-token>

A global Hono middleware verifies the JWT using jose and extracts auth context:

// Accessible in every route handler
const { userId, orgId, role, permissions } = c.get('auth');

All database queries are automatically scoped to orgId. A user from Org A cannot read or modify data belonging to Org B regardless of the URL they request.

Local dev bypass#

Set AUTH_DEV_BYPASS=true in the API .dev.vars file to bypass Clerk JWT verification. Use DEV_AUTH_ROLE and DEV_AUTH_TENANT_ID to simulate a specific user context.

Error response format#

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation",
    "details": {
      "fieldErrors": {
        "name": ["String must contain at least 1 character(s)"]
      }
    }
  }
}

Zod validation#

Every route that accepts a request body uses @hono/zod-validator. A request body that fails schema validation returns a 422 with field-level error details before the route handler is ever called.

Route groups#

All routes are under /api/ prefix. Routes are grouped by module and mounted in apps/api/src/index.ts.