API Security Model

Overview

apps/webapp uses a defense-in-depth authentication model for /api/* routes implemented across three layers:

Explicit route-prefix categorization in apps/webapp/src/middleware.ts — categorizes routes into Public, Admin, Organization-Required, and Auth-Only prefixes.
Uncategorized-route enforcement in apps/webapp/src/middleware/api-auth-enforcement.ts — evaluates any /api/* route against apps/webapp/src/lib/api/auth-allowlist.ts (PUBLIC_API_EXACT_PATHS and PUBLIC_API_PREFIX_PATHS).
Handler-level guards in BaseAPIHandler (apps/webapp/src/lib/api/base-handler.ts) — route handlers explicitly call requireAuth(), requireAdmin(), requireOrganization(), or validateInternalServiceToken().

Route Categories in `middleware.ts`

1. Public API Routes (`PUBLIC_API_ROUTES` & `auth-allowlist.ts`)

Routes that handle their own authentication (e.g., webhook signatures, service tokens, OAuth 2.1 / PKCE flows) or are intentionally public health probes:

/api/health (and /api/health/ready, /api/health/redis, /api/health/schema) — infrastructure & schema health probes
/api/contact — public contact form submissions
/api/webhooks & /api/webhook/* — Clerk, Stripe, inbound email, forwarding confirmation, and Zendesk webhooks (verified via HMAC signatures or validateInternalServiceToken)
/.well-known/*, /api/oauth/*, /api/mcp/* — OAuth 2.1 Authorization Server metadata, JWKS, Dynamic Client Registration, and token endpoints for ops-mcp
Internal service-token routes in PUBLIC_API_PREFIX_PATHS (/api/alias/, /api/email/triage, /api/eval/, /api/inbox-routing/internal/, /api/orders/missed-reconciliation/, /api/billing/internal/) — guarded by header secrets via validateInternalServiceToken

2. Admin API Routes (`ADMIN_API_ROUTES`)

Require an authenticated Clerk session belonging to a system administrator (isUserAdmin(user)):

/api/admin/* — system administration
/api/sys-admin/* — platform operator controls
/api/cache/* — Redis cache inspection and flushing
/api/maintenance/* — maintenance operations
/api/debug/* — diagnostic endpoints
/api/tests/* — test harness endpoints

3. Organization-Required API Routes (`ORG_REQUIRED_API_ROUTES`)

Require both an authenticated Clerk user session and an active organization context (clerk_organization_id), verified against organization membership:

/api/erp/* — ERP connections, catalog search, quote generation, and order submission
/api/orders/* — order CRUD, revisions, and feedback
/api/extracted-orders/* — extracted order review state
/api/pdf-documents/* — document upload and retrieval. Exception: POST /api/pdf-documents itself is runtime-public (apps/webapp/src/lib/api/auth-allowlist.ts) because it is mixed-auth: source=manual calls requireAuthFromLocals, while source=external (the Cloudflare email worker) has no Clerk session and is authenticated by an X-Inbound-Email-Signature HMAC over {filename, connectionId, organizationId}, whose organizationId must own the connection. Sub-routes such as /api/pdf-documents/[id] are not allowlisted and do require a session.
/api/inbox/* — unified inbox queries and bulk actions
/api/emails/* — email threads, connections, and labels
/api/alias/* — organization email aliases
/api/billing/* & /api/subscriptions/* — Stripe billing and usage analytics
/api/organizations/* & /api/settings/org-rules/* — organization settings and routing rules
/api/temporal/workflow/* — workflow status polling
/api/analytics/* & /api/analytics-admin/* — product and operational metrics
/api/audit/*, /api/notifications/*, /api/support/*

4. Auth-Only API Routes (`AUTH_ONLY_API_ROUTES`)

Require an authenticated Clerk user session, with organization scoping resolved inside the handler:

/api/auth/* — session and user profile endpoints
/api/work-items/* — work-item state transitions and snooze controls

Uncategorized API Route Enforcement (`AUTH_ENFORCEMENT_MODE`)

apps/webapp/src/middleware/api-auth-enforcement.ts runs on every /api/* request not matched by PUBLIC_API_EXACT_PATHS or PUBLIC_API_PREFIX_PATHS:

AUTH_ENFORCEMENT_MODE=log (current default): If no authenticated locals.userId is present, the middleware logs a structured warning (AUTH_ENFORCEMENT: would block) with { path, method } and passes the request to the route handler (return next()).
AUTH_ENFORCEMENT_MODE=enforce: Immediately rejects unauthenticated requests at the middleware boundary with HTTP 401:
```
{
  "error": "Unauthorized"
}
```
AUTH_ENFORCEMENT_MODE=off: Disables the enforcement check.

Handler Implementation Patterns

Admin Endpoints

class AdminHandler extends BaseAPIHandler {
  async GET({ locals, request }: APIContext): Promise<Response> {
    return this.handleRequest(async () => {
      const { userId } = await this.requireAdmin(locals, request);
      // Admin-only logic...
    });
  }
}

Organization-Scoped Endpoints

class OrderHandler extends BaseAPIHandler {
  async POST({ locals, request }: APIContext): Promise<Response> {
    return this.handleRequest(async () => {
      const { userId, organizationId } = await this.requireOrganization(locals, request);
      // Every DB query MUST filter by organizationId (clerk_organization_id)
    });
  }
}

Internal Service-to-Service Endpoints

Routes called by temporal-worker, ts-temporal-worker, or email-worker must validate a shared service token using constant-time comparison (validateInternalServiceToken in apps/webapp/src/lib/api/validate-internal-token.ts):

import { validateInternalServiceToken } from '@/lib/api/validate-internal-token';

const authResult = validateInternalServiceToken(request, process.env.INTERNAL_SERVICE_TOKEN);
if (!authResult.valid) {
  return new Response(JSON.stringify({ error: authResult.error }), { status: authResult.status });
}

Adding a New API Route Checklist

Choose the auth model:
- User-facing tenant route → add prefix to ORG_REQUIRED_API_ROUTES in apps/webapp/src/middleware.ts and call requireAuth / requireOrganization in the handler.
- System admin route → add prefix to ADMIN_API_ROUTES and call requireAdmin.
- Worker/webhook route → if it uses its own signature or service token, register the path in apps/webapp/src/lib/api/auth-allowlist.ts and verify the signature/token at the top of the handler.
Scope every query by tenant: Always include eq(table.clerkOrganizationId, organizationId) or eq(table.connectionId, connectionId).
Add tests: Include an unauthenticated 401 test and a cross-organization 403/404 isolation test.