Request flow
Understanding request flow prevents mixing concerns: TLS/SNI, tenant resolution, JWT verification, PostgREST routing, and Postgres permissions are different failure modes.
What you will learn
- v2 shared path step-by-step
- How v1 differs
- Where to look first when debugging
The idea
v2 shared
HTTPS client → Traefik / edge (TLS; exact pooled host discovered from the catalog) → Flux gateway (host → tenant, verify project JWT) → PostgREST pool (bridge JWT → role) → Postgres (tenant schema, policies)
v1 dedicated (typical)
HTTPS client → Traefik (host → tenant API container) → PostgREST (project keys / JWT per container env) → Postgres (per-project instance)
How it works
Each layer refuses with a recognizable signal: 401 before Postgres indicates auth at the edge; 42501 indicates database authorization; an empty array indicates RLS filtering after the role was already allowed in. The full layer-by-layer map and verification steps live in Troubleshooting.
For pooled projects, the control plane renders exact Host(...) routers into Traefik's watched dynamic configuration whenever the catalog changes and again at startup. That exact rule is what lets the ACME resolver request a trusted certificate for a newly created canonical Service URL; the gateway's broader host matcher remains the data-plane routing fallback, not the certificate inventory.
Example
For internal health checks from the control plane, prefer probing via the gateway with correct Host headers—see Environment variables (FLUX_TENANT_PROBE_GATEWAY_URL).