Supabase Local Manager

Request flow

One API call, from the browser to a project service and back, with every decision in between.

On this page
  1. What it is
  2. Why trace it
  3. One request, step by step
  4. Where the paths converge
  5. Decision table
  6. Failure and recovery
  7. Where to look when it fails

What it is

This page follows one request from a browser to a project service and back. It is the concrete version of the architecture: resolution, access, forwarding, response rewriting and the log entries that record the decision. The same path serves a manager API call and a project API call, with one difference: a management call stops at the manager, while a project call is forwarded to the project's gateway or Studio.

Why trace it

Most confusing local failures are path failures. The request went to the wrong project, the wrong service, or the wrong origin after a redirect. A trace makes each decision visible, so a 401, a 403 and a 404 stop being interchangeable symptoms and become specific answers.

One request, step by step

Request flow sequence A browser calls the manager API with a session cookie and CSRF header. Middleware verifies the session and CSRF token, the route checks project ownership, the backend queries the manager database or project Postgres, and the response returns as JSON to the browser. A manager API request, end to end BrowserExpressMiddlewareRouteStore GET /api/projects/:id/status session cookie verify + CSRF + ownership route handler manager DB / Postgres rows / status 200 JSON Failure paths Missing or invalid session gives 401. CSRF mismatch gives 403. A non-owner gets a non-disclosing 404. An upstream failure goes through central error redaction; no stack trace reaches the browser.

Diagram: a browser request is resolved by the front door, evaluated for access, forwarded to Kong or Studio, and the response is rewritten before it returns to the browser.

ClientDecisionProject

The sequence

  1. The client sends a request

    It targets the front door origin, a project's front-door path and an endpoint such as /rest/v1/items. A manager session cookie or a project API key travels with it.

  2. The entry point resolves the project

    Path routing reads the first segment as the database link; host routing reads the Host header. An unknown identifier stops here with a canonical 404.

  3. The access evaluator decides

    A manager session is checked for ownership or admin role. Otherwise a project key is checked, but only for Kong service paths. The postgres-meta path additionally requires the service-role key.

  4. The forwarder rewrites and sends

    The link prefix and the manager token are removed. The request goes to the project's Kong port for service paths, or its Studio port for the SPA and its assets.

  5. The response is re-scoped

    Set-Cookie paths are prefixed with the project link, and internal Location redirects are rewritten onto the client's origin before the response returns.

Where the paths converge

Front-door and subdomain routing A client request reaches either the path-routed front door on port 6000 or the host-routed subdomain proxy on port 9000. Both resolve a project and run the same access evaluator before forwarding to Kong or Studio for that project. Two entry points, one access policy Clientsupabase-js, curl,Studio, browser app Front door:6000/<database-link>/…resolveByPath Subdomain proxy:9000 · slug.base-domainresolve by Host header evaluateFrontDoorAccess manager session + ownership or project anon / service key unknown link → 404 non-owner → same 404 Kong gatewayREST · Auth · StorageRealtime · Functions Studioproject SPA routesnever opened by an API key legend entry point shared policy policy check

Diagram: the path-routed front door and the host-routed subdomain proxy converge on the same access evaluator, then diverge to the project's Kong gateway or Studio.

EntryPolicyDenial

Decision table

The evaluator's outcomes are deliberately small. An unknown link is a 404 with a canonical body. A non-owner is a 404 of the same shape. A known link with no valid credential is a 401 in the shape Kong clients expect. An anon key on the postgres-meta path is a 403. A valid manager session or a valid project key on an allowed path is forwarded. An API key never opens Studio, even when the key is valid, because Studio is a manager surface rather than a project API.

Failure and recovery

If the project is stopped, forwarding fails at the upstream connection. If the project restarted and its ports changed, the saved allocation is what the front door reads, so the manager must have completed the start before the request is retried. Denials are logged with the entry point, so a front-door denial and a subdomain denial can be told apart. A client that receives a 401 should check its key; a client that receives a 404 should check the link and its own ownership, because the two failures deliberately look the same from outside.

Timing matters as well. A project start writes its configuration and then invokes the CLI, so a request sent during the start can reach a gateway that is not listening yet. Retry after the project reports running rather than interpreting the first connection failure as a routing fault. Likewise, a restart can briefly change the upstream port; the front door reads the saved allocation, so wait for the start to settle before concluding that the link is wrong.

Configuration

<code>FRONT_DOOR_PORT</code>
The port this trace enters.
<code>PROXY_PORT</code>
The alternative host-routed port.
Log retention
Bounds how long a denial entry remains available.
A 404 is not always a routing mistake. For a caller that does not own the project, it is the intended non-disclosing answer.

Where to look when it fails

The entry point and the access decision are logged. If a request never appears in the project's own logs, it was denied or misrouted before forwarding. If it appears in the gateway log but not in the service log, the gateway reached the project and the service did not answer. If it appears in both, the problem is in the response path or the client.

That ordering turns a vague failure into a location. It is also why the front door and the subdomain proxy tag their denials with the entry point: the same policy can be exercised from two places, and the log says which one.

Related

Front doorThe entry point that starts the trace.Port bandsWhere the destination port comes from.Logs and observabilityWhere the request appears afterwards.