API

Routes served by the loopback server (lab/upstream-server.ts). Paths starting with /management/ are the management API, /v1/ and /mcp are for agents, and everything else is the application gateway. Read from the code on 2026-10-19; the code is authoritative:

• Routing between the three groups: src/control/application.ts
• Management metadata: src/control/http.ts
• Keys and connection details: src/control/key-http.ts, dispatched by src/control/handler.ts with the Studio, Realtime, sign-in, Edge Functions, database, signing key, share and invitation routes beside them
• Access tokens, /v1 and /mcp: src/control/access-token-http.ts, src/control/supabase-api.ts, src/control/mcp.ts
• Gateway: src/gateway/managed.ts, src/gateway/handler.ts, src/gateway/concurrency.ts

The console and its static assets are served beside these routes by lab/ui-static.ts. The loopback server refuses any Host other than 127.0.0.1 or localhost; public exposure goes through a TLS proxy (see server deployment).

Management login

Proxied to the dedicated management Auth realm, with the publishable routing key sb_publishable_sbarbase_local_management. Point the Supabase SDK at <base URL>/management.

Any other /management/auth/... path is 404; a wrong method is 405. Sign-in attempts are rate limited and answer 429 past the limit.

Management API

All routes need Authorization: Bearer <management access token>. The actor comes from that token, never from the body. IDs are UUIDs. Errors: 400 invalid input, 401 no valid token, 403 not allowed (also for an unknown ID), 404 unknown route, 405 wrong method, 409 conflict (environment not ready, name already used in that client or project, environment limit reached, not retryable, still holds projects or environments, provisioning or a service still active); nothing was changed, 503 identity check unavailable, 500 sanitized internal error.

Request bodies accept exactly the fields listed for the route, at most 4 KiB, read within five seconds. Key and connection routes and every DELETE refuse any body. Responses are not cacheable. A move revokes API keys but does not rotate the environments' JWT signing key or direct database password; rotate them (signing key) when people of the old client must lose every kind of access. Deleting an environment does not free its slot in the worker's environment limit, because its runtime is kept. On an ordinary installation, deleting an environment always answers 409 with "Exact ownership inventory unavailable" and changes nothing. Provisioning does not record the exact list of an environment's resources, and none could be recorded honestly: every environment shares the PostgreSQL cluster and the Storage process, and nothing yet proves that a database and its Storage files are written by that environment alone, so the lifecycle refuses any list that names them. Only the lifecycle probes reach a successful delete, on disposable fixtures. Restore and purge start from a deleted environment, so they cannot be reached either.

Agents: the Supabase-compatible API and MCP

With an access token as Authorization: Bearer sbp_...: /v1/... answers the part of Supabase's Management API that agents and tools use, and POST /mcp runs Supabase's own MCP server against it. What each does here and its limits are in AI agents and the API. An access token is refused by every /management/ route. A project {ref} is one environment, 20 lowercase letters.

Deleting, pausing or restoring a project and generating types answer 501 with what to do instead; any other /v1 path answers 404.

Updates

The update channel's routes (upgrades), in src/control/http.ts and src/control/updates.ts. Only the installation operator (an owner or admin of the client created at bootstrap) may call them; anyone else gets 403. The console only reads and asks: the supervisor carries out each request after judging it again, and publishes its verdicts in .lab/upgrades/current.json.

Every request route answers 409 with "Another update request is still in progress" while another request holds the slot. While a new version waits for its health checks, reads, the management sign-in, check, settings and rollback pass; every other management change answers 409 with a sentence saying changes are paused, and application routes answer 503 with Retry-After: 5. The supervisor's own health probe passes the hold on REST and Auth only, with a per-start token and never with x-forwarded-* headers (src/gateway/hold-bypass.ts).

Loopback health

GET /health (or HEAD) on the loopback listener, for 127.0.0.1 or localhost only, needs no token. It answers 200 {"status": "ok", "held": bool} once the process serves and both the control catalog and the key store read, and 503 {"status": "unavailable"} otherwise; any other method is 405. held says whether application traffic is held for an update. The supervisor's health round after an update starts with this route (src/http/health.ts).

Application gateway

{METHOD} /{runtime}/auth/v1/{path}
{METHOD} /{runtime}/rest/v1/{path}
{METHOD} /{runtime}/storage/v1/{path}

{runtime} is the environment's runtime ID returned as apiPath above. Point supabase-js at <base URL>/{runtime} with a publishable key.

• Methods: GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS for a browser's preflight.
• Browsers: as on Supabase, a page on any domain may call the API. Every answer, refusals included, carries Access-Control-Allow-Origin: * and exposes Content-Range; a preflight gets 204 without a key. No cookies or credentials are used, so the API key and the user token still decide everything a call may do.
• API key: the apikey header must be an active publishable or secret key of that environment. A secret key is refused with 401 when the request looks like a browser's (a Mozilla/ user agent, an Origin or a Sec-Fetch- header). The only keyless requests are GET or HEAD on Storage object/public/... and on object/sign/... with exactly one token query parameter, where Storage itself enforces bucket visibility and signature validity; and the Auth steps a browser reaches by a link or a redirect: GET verify, GET authorize, and GET or POST callback, which Auth checks itself.
• Authorization: a Bearer user token is forwarded; if absent (or equal to the API key) the environment's anonymous token is used, or a short-lived service_role token for a secret key.
• Storage tenant: chosen by the gateway from the routing record and sent as a trusted header; a client cannot choose it.
• Body: at most 1 MiB, read within ten seconds. A file upload to Storage (POST or PUT) is passed on as it arrives, up to the upload limit (SBARBASE_UPLOAD_LIMIT_MB, 50 MiB by default), and fails if it stalls for thirty seconds.

Admission limits are per gateway process and have no queue.

Realtime

When an environment has Realtime turned on (Realtime):

With Realtime off, the socket answers 404. A wrong or revoked key answers 401. Every other Realtime path answers 404.

Edge Functions

When an environment has functions deployed (Edge Functions):

A name is letters, digits, - and _, at most 64, starting with a letter or digit; anything else, an unknown function or Edge Functions turned off answers 404. A function that checks JWTs answers 401 to a missing or invalid token. The deadline is 150 seconds; bodies stream up to the upload limit.

Edit on GitHub