Public Route Namespace Convention

This document defines route namespace boundaries for unauthenticated and semi-public surfaces.

Namespace map

• /api/guest/*

  • Purpose: anonymous trial workflows (guest uploads/audits).
  • Auth: guest-token model.
  • Data scope: sandboxed/ephemeral trial path.

• /api/public/signup/*

  • Purpose: self-serve signup bootstrap and provisioning state machine.
  • Auth: unauthenticated.
  • Feature gate: SELF_SERVE_SIGNUP_ENABLED.
  • Flag-off behavior: 503 FEATURE_DISABLED with retryAfterSeconds.

• /api/public/billing/*

  • Purpose: billing setup bootstrap for tenant integrations.
  • Auth: authenticated integration token.
  • Tenant guard: tenant must be active.
  • Current endpoint: POST /api/public/billing/setup-session.

• /api/* tenant product routes

  • Purpose: core product operations.
  • Auth: Clerk or integration token.
  • Tenant guard: tenant must be active unless explicitly exempted.

Middleware rules

1. /api/public/signup/* bypasses active-tenant guard.
2. /api/guest/* keeps its dedicated guest auth boundary.
3. Any new /api/public/* route must document:
   • auth model,
   • tenant-status behavior,
   • feature-flag behavior (if gated).

OpenAPI requirement

Any public namespace route added to production must be included in docs/api/openapi/rgl8r-public-api-v1.1.0.yaml before release.