Skip to content

SupabaseTenancy and placementguide

Running a platform on the Supabase Management API

The Management API makes projects, keys, config, usage and lifecycle programmable. The docs cover the endpoints but not the platform layer on top of them: the provisioning loop, the rate budget, the metering, the OAuth paths and the pause playbook. This guide covers that layer. Every number in it was measured against the live API on throwaway projects, on 2026-08-17/18 unless the text carries another date (later checks run to 2026-10-13); where something is gated or untested, it says so. To follow along: a Supabase org on a paid plan, a personal access token with Management API access, and throwaway projects you will delete when done. The placement doc decides where a tenant should live; this guide is the mechanism that puts it there.

The shape being built:

Your product(tenant-facing UI)Control planeprovisioning service + tenant->ref mapusage poller + rate-budgeted clientCredential-proxy gateway(optional; PAT stays server-side,scoped keys go out)api.supabase.com/v1projects / config / addons / analyticsdirect is fine at small scaleTenant poolone project per tenant(or shared tier - see placement doc)
  1. Your product (tenant-facing UI) -> the control plane.
  2. Control plane (provisioning service, tenant->ref map, usage poller, rate-budgeted client) -> the credential-proxy gateway, and -> api.supabase.com/v1 directly if the scale is small.
  3. Credential-proxy gateway (optional: the PAT stays server-side, scoped keys go out) -> api.supabase.com/v1.
  4. api.supabase.com/v1 (projects / config / addons / analytics) -> the tenant pool: one project per tenant, or a shared tier.

Two integration shapes, differing on who owns the Supabase organization and the billing relationship:

  • You provision on their behalf - your org, your PAT, one project per tenant, users never see Supabase. White-label, you hold the billing relationship. The rest of this guide is this shape.
  • They bring their own backend - the user’s org, connected to your app through the Management API OAuth2 flow. You get a scoped token; they keep the direct billing relationship. Section 5 has the measured surface.

You can offer both. The project-claim flow is the bridge from the first to the second when a tenant outgrows you: GET /v1/oauth/authorize/project-claim with the project ref and your OAuth app’s client_id sends the user through sign-in, organization choice and consent, then transfers the project to their organization while your OAuth integration keeps access to it.1 The public v1 spec lists that route as GET only.2 The claim flow has not been run here. For a time-boxed, network-restricted, role-scoped grant instead of a full project handover, use the JIT database access grant routes. On a Pro org (Postgres 17, measured 2026-10-10) PUT /jit-access with {state} and PUT /database/jit answered 200 in all five runs (JA01c, JA01d). The invite route, POST /database/jit/invite (email + role + expires_at + allowed_networks CIDRs), was rejected on a Pro org with a 500 (measured 2026-08-25, S15), so on Pro use the grant route and do not use the invite route. The grant route needs SSL enforcement on first, takes the key roles and reads expires_at as epoch seconds; the JIT database access page has the measured surface.

Documented: scoped tokens “start with sbp_fc” and carry only the organisations, projects and permissions chosen at creation; they are created from the access tokens settings in the Dashboard, with an expiry up to one year out.3 The GA changelog adds that supabase whoami does not work with project- or organisation-scoped tokens.4 Both sentences are the reading of a summarising fetch on 2026-10-10, not a verbatim copy.

Measured 2026-10-10 (SP01, SP05, SP06, one run each, a Pro org):

  • Creation has no /v1 API. The public /v1 OpenAPI document (115 paths, 170 operations) has no access-token creation operation; the only token-named routes are the OAuth token and revoke routes and the project claim-token routes. The open-source Dashboard creates scoped tokens with POST /platform/profile/scoped-access-tokens5 and classic tokens with POST /platform/profile/access-tokens,6 both outside /v1. The classic-token route, GET /platform/profile/access-tokens, answers a PAT 401 {"message":"Unsupported access token"}, while GET /v1/profile/access-tokens and GET /v1/access-tokens answer 404 and GET /v1/organizations answers 200. Only GET was sent, the scoped-token route was not probed, and no token was minted.
  • The lab token has the sbp_fc format; which scope it was created with was not read. With it, GET /v1/profile answers 403 {"message":"This endpoint requires a user-scoped access token"}, and the Supabase CLI 2.120.0 exits 1 on supabase whoami (unexpected get profile status 403) while supabase orgs list and supabase projects list exit 0. That agrees with the changelog sentence and does not test it, because the token’s scope is unknown and “token is scoped” is not separated from “token lacks a user-level grant”.
  • The SQL read-only boundary has a control. select 1 answers 201 on both /database/query and /database/query/read-only; create table through the read-only route is refused with 400 and ERROR: 25006: cannot execute CREATE TABLE in a read-only transaction and the table is absent on read-back, while /database/query answers 201 and the table is present.

Not measured, each with a named prerequisite in the experiment’s run log: an organisation-scoped token (does it create projects, see later projects, and draw on the same request budget as its owner’s token), the per-permission matrix and the body of the 403, SQL read-only without the Database read-write permission, the project boundary of a project-scoped token, whether a token follows its creator’s current role (needs a second human member), revocation latency, and immutability and expiry (Dashboard-only, so doc-cited and not tested). A run of the organisation-scoped module with the lab token standing in created a project (201, 3383 ms), listed, read and deleted it; it describes the lab token, not an organisation-scoped one (SP04).

One call creates a project; the rest is setup around it.

  • POST /v1/projects with organization_slug, a strong generated db_pass, and a region. Create -> ACTIVE_HEALTHY measured 131-159 s on paid Micro, 12-13 s on a free org.
  • Smart region selection works on a normal paid org: region_selection: {type: "smartGroup", code: "apac"} was accepted (201) and the platform picked ap-northeast-2. Defer the city choice instead of pinning per tenant.
  • Fresh projects refuse their first /auth/v1/admin/users write after reporting ACTIVE_HEALTHY: 5 of 5 with 500 unexpected_failure, accepting the second call one poll later (2026-08-04), and 2 of 2 with 500 "Database error checking email" for ~10 s after passing the per-service health poll (2026-08-03). Poll GET /v1/projects/{ref}/health?services=auth&services=rest&services=db, then retry the first write with backoff; do not treat it as a finding.
  • Fetch keys with GET /v1/projects/{ref}/api-keys?reveal=true and select by name OR type - new projects carry both legacy JWTs and the new sb_publishable_/sb_secret_ shapes.
  • Configure services with the config endpoints (auth, PostgREST, storage, realtime, functions + secrets). The OAuth server flips on with PATCH /v1/projects/{ref}/config/auth {oauth_server_enabled: true, oauth_server_authorization_path: ...} - measured 200.
  • Treat a create that failed as possibly landed (2026-10-10). A POST /v1/projects whose answer was lost to a 1 s client cap (LO04), to a 4 s client timeout over an 8 s hold, or replaced by a 500 after upstream created the project (MF02) left 1 project with that name in each case. An identical re-send answers 400 Project with name "<name>" already exists in your organization. (LO04, n=1; MF02), which reads as “look it up by name”. Keep the name stable across retries of one logical create. The same-name 400 is the only duplicate protection observed: a retry that generates a fresh name per attempt is not covered by it and was not run. Control-plane fault behaviour has the per-client retry counts.
Org classNanoFloorPause
Paid (Pro) orgrejected three ways: create 400 Minimum instance size on paid plans is Micro, addon PATCH 400 addon_variant: Invalid input, absent from available_addonsMicro, always-on400 Project is not free-tier
Free orgaccepted (201) - and there is NO compute addon catalogue at allshared/free computefull lifecycle: pause -> INACTIVE, restore wakes in 162-204 s, data API answers HTTP 540 Project paused while parked
Legacy free-era project inside a paid orgn/akeeps its paused state after the upgradeone-way door: once restored it cannot be re-paused - pause follows the org’s current plan, not the project’s lineage

Scale-to-zero pricing is part of the Supabase for Platforms programme: it applies to Nano instances only, the guide says not to pass desired_instance_size when creating a project (its own example request passes "micro"), Micro and larger cannot scale to zero, and only select customers have access.1 On a normal paid org there is no idle discount, which is the cost premise the tenant placement doc is built on.

Measured on a normal paid org, on a cheap scoped read:

  • Every response carries x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset. The limit read 120, decrementing 1:1 per call. Read the header; never infer the budget.
  • A deliberate burst tripped 429 {"message":"ThrottlerException: Too Many Requests"} at request 118 with retry-after: 60 and recovered after the window. The breach on this endpoint is the API’s own machine-readable JSON - but aggressive polling elsewhere has produced a non-JSON interstitial from the edge layer, so treat “non-JSON body” and “JSON 429” as the same back-off signal.
  • The budget is cumulative across a user’s PATs (measured 2026-08-18, L01b, on one cheap scoped read): alternating two tokens from the same user on that route, each token’s x-ratelimit-remaining drops on the OTHER token’s calls - one shared counter per user per scope, on that route. PAT sharding does not multiply the budget on the route measured.
  • x-ratelimit-remaining is a per-route counter at limit 120 (measured 2026-10-10, SP10, one token): the same route read 117, 116, 115, 114 on four calls, and two alternated routes (/organizations, /projects) kept separate sequences (113 then 112, and 118 then 117). A two-token comparison is valid only on one route; across two routes it shows two counters, not two budgets. The Management API introduction documents 120 requests per minute, per user, per project or organisation, per endpoint7; SP10 agrees with the documented scope. Whether the header separates two tokens of one user on a given route was not re-measured in SP10, which used one token.

At fleet scale, build the client as a queue with a token bucket.

The OAuth2 flow for the Management API: register an OAuth app, the user approves, you hold a scoped access/refresh pair.8 Measured surface on a normal paid org:

  • Unknown client_id at /v1/oauth/authorize -> 422 {"message":"Unrecognized client_id"}. Client validation fires before session validation, so the no-session redirect is only observable with a real client_id.
  • The token lifecycle, measured 2026-08-18 after a real consent: refresh grants return 24-hour access tokens AND a NEW refresh token every time - rotate or lose the grant. The token is org-scoped: it sees exactly the org approved at consent (1 org, its 3 projects), not the account’s other orgs. Revocation answers 204 and the refresh grant fails immediately with 404 - zero measurable lag.
  • The jwt-bearer token grant validates parameters before any gating (422 Required parameter: client_id).

The project’s OWN OAuth 2.1 server (Supabase-as-IdP for third-party apps) is a separate surface. It is fully headless-automatable and its tokens carry client_id, which RLS can read. Measured 2026-08-18: auth.jwt() ->> 'client_id' in a policy showed a row to the matching client’s token and hid it from a second client of the same user, so a shared project can hold per-client permissions as well as per-user ones.

Metering has three layers, all measured. Per-project cost attribution is the full build, and also covers the non-tenant case of one consolidated org wanting per-project chargeback.

  1. The invoice already itemises usage per project ref (compute, disk, egress, storage, PITR, custom domains) with quantity and rate. The plan fee, monthly active users (MAU), function invocations, realtime, and discounts are org-level aggregates, so splitting them per tenant takes an allocation policy.
  2. Between invoices, estimate from the compute SKU in billing/addons, pg_database_size() and the Storage listing (exact to the byte), usage.api-counts (exact, ~1 min lag). No per-service egress bytes exist in the public per-project API.
  3. Your own gateway meters in real time: exact for anything transiting it, and scoped keys mean no god-mode PAT in scrapers (measured: 200 with 278 metric families for the allowed key, 403 deny-by-default elsewhere, ~1 s audit flush).

7. Move tenants when they outgrow the placement

Section titled “7. Move tenants when they outgrow the placement”

Cross-project trust (third-party JWKS) makes a tenant’s tokens verifiable on their new project, with two measured edges: refresh only works at the issuing project (400 refresh_token_not_found verbatim at the trusting one), and key rotation needs a maintenance window (the trusting project’s cache does not re-resolve on any observed timeline). The build recipes: shared tier, promotion, consolidation; the decision framework is the placement doc, and what each operation costs in client-visible downtime is in platform operation costs.

  • Deleting a project has a tail: a delete returns ~2 s but the project lingers in lists briefly; batch deletes need canary batches.
  • An auto-paused project loses its public DNS record. The data API answers HTTP 540 Project paused right after a manual pause on a free org, but two free-plan projects that auto-paused answered NXDOMAIN on independent public resolvers, with db.<ref> gone too (read 2026-09-23). A client has to handle the resolution failure as well as the 540.
  • Restores are slow: a legacy project exceeded a 20-min wake bound before coming healthy; free-org restores measured 162-204 s. Wake ahead of the user, not on their click.
  • Parking has a duration too (2026-10-13, Z01, one run on a free-plan project): POST /pause reached INACTIVE in 62 s through PAUSING, and POST /restore reached ACTIVE_HEALTHY in 181 s through COMING_UP and RESTORING.
  • Four project-scoped reads answer 200 with an empty result on a parked project rather than an error (2026-10-13, Z01, the same run), so a status code cannot separate “nothing to report” from “could not look”: GET /api-keys returned [], GET /advisors/performance and GET /advisors/security returned {"lints":[]} and GET /config/database/pooler returned [], each after answering with content while awake. The run seeds a public table with RLS disabled before the awake pass, so the security advisor has a finding to lose. A fleet-wide advisor or key sweep scores every parked tenant clean.
  • Sixteen of the 52 parameter-free project GETs answer a different status code when the project is parked (2026-10-13, Z01).
  • There is no API-observable pause timestamp. In the public v1 spec the project object carries status and created_at and no pause time, the organization listing adds inserted_at, and /actions lists action runs rather than lifecycle events,2 so a check-back later reads the state as a binary and the moment it changed exists only if something was sampling when it happened.
  • Plain project GETs return credential material to a PAT holder, and the public v1 spec documents it: GET /v1/projects/{ref}/postgrest carries jwt_secret in its response schema, GET /v1/projects/{ref}/api-keys carries api_key and takes a reveal parameter, and both name a secret-read permission (data_api_config_secret_read, api_gateway_keys_secret_read) in x-fga-permissions.2 A classic PAT is full project access rather than a read-only analytics credential.
  • Free-plan projects auto-pause on their own. Two free-plan projects, idle from 2026-09-09, read INACTIVE at the 2026-09-23 check-back, including a control nothing had touched after its create call. Run an auto-pause arm against free-plan projects; a Pro project cannot pause (section 3).
  • Hibernation was not reachable on any account available here (2026-09-09). Four ladder rungs up to 2 hours idle on a free-plan nano project returned no project_hibernating in validation_errors, and the first request of each rung cost 0.447-0.763 s against 0.047-0.082 s on the follow-ups that came after it - a penalty that does not scale with idle length, since 122 minutes looked like 32. A wake check therefore needs a threshold over 3 s rather than “elevated over baseline”; the four longer rungs (4 h to 48 h) never ran.
  • Two arms exist as modules that have never run. Z02, the write surface, has never run as a module, so no write result is published here; Z04, which fires wake candidates at automatically paused projects, has never fired, so the zero-waker result covers manually paused projects and parameter-free reads only.

Measured 2026-10-10 on a Pro org in ap-southeast-1 (MF01 to MF05). Every fault was injected through a local proxy in front of api.supabase.com; no real 5xx was observed, so how each client reacts to a real 5xx body (an HTML interstitial, say) is not measured. error-before means the proxy answered without contacting upstream; error-after means it forwarded the request, upstream completed it, and the proxy replaced the answer with the error. Attempt counts are proxy-log rows. One trial per cell; the development and final runs gave the same counts wherever both measured a cell.

ClientReads (GET)Writes (POST, PUT, DELETE)Slow answer
Lab harness mgmt() (MF01, MF02)1 attempt on 500, 502, 503 and 504; the status is returned, not thrownno retry; the caller gets the 500throws TimeoutError at 30001 ms on its 30 s default; the proxy still forwarded and upstream answered 200
Lab harness functionPresent() (MF01)retries 429 only, a fixed 15 s sleep: 3 attempts in 30144 ms for two 429s; a 500 on the read returns present: false with status 500 after 1 attemptn/an/a
supabase CLI 2.120.0 (MF03, MF05)6 attempts on 500, 502, 503 and 504, 3-4 ms apart first to last, exit 1; five 500s then upstream healthy: 6 attempts, exit 0; six 500s: exit 1; 429 is not retried (1 attempt)PUT (ssl-enforcement update) and DELETE (projects delete, domains delete) on 500: 6 attempts each; POST (projects create, secrets set) on 500: 1 attempt; POST secrets set on 502, 503, 504 and 429: 1 attempt each60 s per attempt: a 100 s hold gave attempts at 0, 60, 120, 180, 240 and 300 s and exit 1 after 360220 ms; a held POST is not resent, so projects create held 75 s exited 1 after 60448 ms while the project was created
OpenTofu 1.13.1, provider supabase/supabase 1.11.0 (MF04, MF05)project read: 4 attempts on a persistent 503 (plan exit 1 after 6240 ms), 2 attempts on a single 500 or a single 429 (plan exit 0)POST, PATCH and DELETE on 500: 1 attempt, not retrieda 100 s hold on the project read: 1 attempt, plan exit 0 after 103298 ms; a create held 130 s: apply exit 0 after 132978 ms, 1 POST
  • A create answered 500 after upstream created the project leaves the provider’s state empty and an orphan upstream. The plain re-apply sends 1 POST and gets 400 (the name exists in the org), leaving the orphan; after the orphan was deleted through the API, the re-apply exited 0 in 3468 ms with 1 resource in state (MF04). The provider’s own error text in the first lines was only “Client Error”. The CLI leaves the same orphan: projects create answered 500 after upstream created it exits 1 with 1 project carrying the name (MF03). tofu import of the orphan was not run.
  • Partial applies converge as follows (MF04, one trial each). A settings write answered 500 before upstream leaves the project in state and the settings not: the next plan exits 2. A settings write that landed upstream but answered 500 converges: the next plan exits 0 with no pending change. A DELETE that landed but answered 500 leaves a state entry that the next destroy removes cleanly, because the GET and DELETE both answer 404 and the provider accepts that.
  • No tool duplicated a POST in any trial (MF05); the same-name 400 is the only duplicate protection observed (MF02).
  • Not measured: real 5xx bodies, connection-level faults (reset, refused, TLS or DNS failure), PATCH through the CLI, writes answered 502, 503, 504 or 429 in the provider, other provider resources, and any documented retry or idempotency behaviour of the CLI, the provider or the API (no docs were read for this).
ClaimHow it was checked
Create -> healthy 131-159 s paid / 12-13 s freeMeasured 2026-08-17/18, n=5+ on paid
Smart region accepted on a paid org, picked ap-northeast-2Measured 2026-08-17
Nano rejected three ways on paid, accepted (201) on freeMeasured 2026-08-17/18
Legacy project: paused survives upgrade, cannot re-pauseMeasured 2026-08-18 - 400 Project is not free-tier
Rate-limit headers + JSON 429 with retry-after: 60Measured 2026-08-17 - burst to the boundary
OAuth authorize: 422 client validation firstMeasured 2026-08-17
Project IdP: client_id claim usable in RLSMeasured 2026-08-18 - headless Proof Key for Code Exchange (PKCE) flow, two-client isolation
Metering: exact ground truth, exact 13/13 analytics at 61 s lag, no per-service egress in the APIMeasured 2026-08-17/18
Scoped-key gateway: 200/278 families, 403 deny-by-default, ~1 s auditMeasured 2026-08-18 against a live credential-proxy deployment
Refresh only at the issuing projectMeasured 2026-08-18 - 400 refresh_token_not_found verbatim
Parked: 52 GETs, zero wakersMeasured 2026-10-13 on a free-plan project - Z01, one run; the write surface (Z02) has never run as a module, so no write result is published here
Parked: 16 endpoints change status code, 4 answer an empty 200Measured 2026-10-13 - Z01, one run, with a seeded security-advisor finding
Pause 62 s, restore 181 sMeasured 2026-10-13 - Z01, one run on a free-plan project
No hibernation to 2 h idle; first request 0.447-0.763 s against 0.047-0.082 s follow-upsMeasured 2026-09-09 on a free-plan nano project, 4 rungs of 8
Free-plan projects auto-pause, including an untouched controlRead 2026-09-23 on 2 free-plan projects idle since 2026-09-09
The public /v1 document has 115 paths and 170 operations, with x-fga-permissions declared on 164 of the 170 (73 distinct names)Measured 2026-10-10 - SP01 read the document. SP02 generated 59 probes from the extension and sent them with the lab token: 53 answered 2xx, 0 answered 403 with missing_permissions, and 6 answered another 4xx that looks like a feature-absent answer (402, 400, 406, 410, 400, 400; read from the status codes, not the bodies). For those 6 the permission check may not have been reached. The reading of the extension (outer list OR, inner list AND) is a hypothesis until a narrow token runs
Scoped-token creation has no /v1 operation; the classic-token Dashboard route GET /platform/profile/access-tokens answers a PAT 401 Unsupported access tokenMeasured 2026-10-10 - SP01, GET only; the scoped-token route /platform/profile/scoped-access-tokens was not probed
GET /v1/profile 403, supabase whoami exit 1, orgs list and projects list exit 0, with an sbp_fc lab tokenMeasured 2026-10-10 - SP06, CLI 2.120.0; the token’s scope was not read
/database/query/read-only refuses create table with 25006; /database/query creates itMeasured 2026-10-10 - SP05, the control for a read-only scoped token
x-ratelimit-remaining is a per-route counter at limit 120Measured 2026-10-10 - SP10, one token, same route 117, 116, 115, 114; two alternated routes keep separate sequences
Grant routes PUT /jit-access and PUT /database/jit answer 200 on Pro; the 500 is the invite routeMeasured 2026-10-10 - JA01c, JA01d, 5 runs, Postgres 17; the invite route on Pro was not re-run (the 500 is S15, 2026-08-25)
CLI retries: GET, PUT and DELETE 6 attempts on 500, POST 1; provider retries GET only; harness mgmt() never retriesMeasured 2026-10-10 - MF01 to MF05, every fault injected through a proxy, one trial per cell
A create whose answer was lost still creates the project; the identical re-send is 400 on the nameMeasured 2026-10-10 - LO04 n=1 and MF02; a fresh-name retry not run

A practice with no module id is a design choice rather than a result: canary batch sizes and token-bucket parameters beyond 120 per minute per user are unmeasured. No parameter-free Management API read restarts a parked project’s compute: all 52 parameter-free project GETs were run against a manually paused project on a free-plan org (2026-10-13) and every one left it INACTIVE. The write surface (Z02) has never run as a module, so no write result is published here. POST /pause and POST /restore are excluded, since they change state by definition. An automatically paused project has no public DNS record (NXDOMAIN, including a control project nothing had touched), so there is no hostname for data-plane traffic to arrive at; the 2026-10-13 run did not read DNS.

That result covers PAUSED projects. Scale-to-zero is a separate mechanism, and none of the above was measured against it. The public spec lists project_hibernating as a blocker type in the GET /v1/projects/{ref}/upgrade/eligibility response, separate from the INACTIVE project status,2 and the spec gives it no description; reading that value as the scale-to-zero state is an inference from its name. The DNS teardown was read on auto-paused projects, where traffic has nowhere to arrive, so do not assume the null result carries to a state that keeps its hostname. Treat the two as separate questions.

PracticeEvidenceModule
Run the provisioning service under a dedicated automation user.The rate budget is per user across all its PATs (each token’s x-ratelimit-remaining drops on the other’s calls), on the route measured (x-ratelimit-remaining itself counts per route, so compare two tokens on one route only), so a separate user is a separate 120-per-minute bucket; and a classic PAT reaches every organization the user belongs to, so the user’s membership set is its blast radius. Use a scoped PAT limited to the platform organization: a probe found no scope endpoint on /v1 (2026-08-03; later codified as F03), but the Personal Access Tokens guide now documents scoped tokens created in the dashboard.3 Project creation with a scoped token was not measured: the organisation-scoped module has only run with the lab token standing in (2026-10-10).rate-limits L01b (2026-08-18); platform-facts F03; scoped-pats SP04, SP10 (2026-10-10)
Poll GET /v1/projects/{ref}/health?services=auth&services=rest&services=db before the first write on a fresh tenant, then retry the write anyway.2 of 2 fresh projects passed the per-service poll and still failed the first admin/users call (2026-08-03); 5 of 5 refused the first write and took the second (2026-08-04).supabase-lab AGENTS.md, provisioning note (2026-08-03); placement reference, Verified row ‘Create -> healthy, and healthy is not writable’ (2026-08-04, n=5, bash run not in the lab repo)
Enumerate creatable regions per org with GET /v1/projects/available-regions?organization_slug=<slug> before offering a tenant a region picker.A Team org answered 200 with {recommendations, all: {smartGroup[], specific[]}}, 17 specific regions and 3 smart groups; the call without the slug answers 400, and /regions and /projects/regions 404.platform-facts F04c (2026-08-20)
Persist the rotated refresh token before acknowledging the refresh.Every refresh grant returns a new refresh token alongside the 24-hour access token, so a dropped rotation loses the grant (2026-08-18).byo-oauth O01c, O01e (2026-08-18)
Map a 404 on the refresh grant to “revoked, re-consent required”.Revocation answered 204 and the next refresh 404 on the first poll, 0 s lag.byo-oauth O01c, O01e (2026-08-18)
Budget a manual dashboard step per environment for OAuth app registration.OAuth app registration has no API: neither the public v1 nor the v2 spec has an OAuth-app operation (read 2026-11-13),29 and the published spec’s 169 operations held only two org-scoped writes on 2026-08-04, organization creation and the project-claim callback.byo-oauth RUNLOG, the manual drill; platform-facts F05 (2026-08-04)
Use the JIT grant route PUT /database/jit on Pro; avoid the invite route.POST /database/jit/invite was rejected with 500 on Pro (S15, 2026-08-25). On Pro the grant routes PUT /jit-access with {state} and PUT /database/jit answered 200 in 5 of 5 runs (2026-10-10, Postgres 17); the grant needs SSL enforcement on first, the key roles and epoch-seconds expires_at (see the JIT database access page). The invite route on Pro was not re-run.sfp-platforms S15 (2026-08-25, Pro); jit-db-access JA01c, JA01d (2026-10-10)
Mint tenant-facing or worker credentials with POST /v1/projects/{ref}/api-keys and secret_jwt_template, and read them with ?reveal=true.The create response redacts api_key otherwise. The templated role and custom claim reach auth.jwt() on a Pro org. A fresh RPC answers PGRST202 until notify pgrst, 'reload schema'.sfp-platforms S14 (2026-08-25, Pro org)
Size a dedicated project at ci_small or above and enable PITR before promising a tenant read replicas via POST /read-replicas/setup.The setup call answers 400 "Read replicas require a minimum size of small" on a Pro org, and after ci_small it answers 406 "Failed to check for latest completed physical backup"; the chain closed after pitr_7 (setup 204).sfp-platforms S07, S07e (2026-08-25)
Grow disk to 6 GB or more in one step on a 2 GB gp3 volume.The gp3 IOPS floor makes 2 -> 4 GB impossible: on a Pro 2 GB volume on 2026-10-01, 4 and 5 GB answered 400 Invalid IOPS value for gp3 volume 3000, 6 GB 201.compute-disk D11 (RUNLOG, 2026-10-01)
Do not promise tenants a backup time of day from GET /database/backups/schedule on Pro or Team orgs.Pro and Team orgs both answer a structured 402 entitlement_required (feature: backup.schedule); the spec text says Enterprise.sfp-platforms S11 (Pro 2026-08-25; Pro and Team 2026-09-03)
Before restoring a paused free-era project inside a paid org, decide whether it should instead be deleted or moved to a Free org.Once woken it joins the always-on floor (400 Project is not free-tier on the next pause), and the wake exceeded a 20-minute bound.instance-sizing I03 (2026-08-18)
After DELETE /v1/projects/{ref}, poll GET /v1/projects until the ref is absent before reusing the name or counting against a quota.The delete returns in about 2 s and the project lingers in lists.section 8 (lingers in lists); placement reference, Verified row ‘Create -> healthy, and healthy is not writable’ (2026-08-04, n=5, delete about 2 s, bash run not in the lab repo)
Read tenant health from status, never from a 200 on a project-scoped read.GET /api-keys answers [], GET /advisors/performance and GET /advisors/security {"lints":[]} and GET /config/database/pooler [] on a parked project, so a sweep that trusts the body reports parked tenants healthy and lint-free.s2z-wake Z01 (2026-10-13, free-plan org)
Budget a minute or more to park a tenant and three minutes or more to wake it.POST /pause reached INACTIVE in 62 s and POST /restore reached ACTIVE_HEALTHY in 181 s (one run, free-plan project); free-org restores measured 162-204 s (section 3).s2z-wake Z01 (2026-10-13)
Run an auto-pause or hibernation arm against free-plan projects.Two free-plan projects auto-paused between 2026-09-09 and 2026-09-23, including an untouched control, and a Pro project cannot pause; hibernation never appeared up to 2 hours idle on a free-plan project.s2z-wake RUNLOG, 2026-09-23 check-back (no module)
Hand-create each scoped PAT in the Dashboard; budget a manual step per environment.There is no token-creation operation in the 170-operation /v1 document, and the Dashboard’s classic-token route answers a PAT 401 Unsupported access token (2026-10-10, GET only); the Dashboard creates scoped tokens through /platform/profile/scoped-access-tokens, which was not probed.scoped-pats SP01 (2026-10-10)
Probe a token with GET /v1/organizations, not supabase whoami.With an sbp_fc lab token GET /v1/profile answers 403 and supabase whoami exits 1, while supabase orgs list and supabase projects list exit 0 (CLI 2.120.0; the token’s scope was not read).scoped-pats SP06 (2026-10-10)
Treat a failed project create as possibly landed; list by name before re-applying.A 500 after upstream created the project, or a lost answer, left 1 project with the name (CLI, harness and provider); the provider’s state stayed empty and the re-apply got 400 until the orphan was deleted.mgmt-api-faults MF02, MF03, MF04 (2026-10-10, injected faults); lifecycle-ops LO04 (n=1)
Keep the project name stable across the retries of one logical create.The identical re-send answered 400 on the name and left 1 project (LO04, n=1; MF02); a fresh-name retry is not covered by that check and was not run.lifecycle-ops LO04; mgmt-api-faults MF02 (2026-10-10)
Do not wrap mgmt() POSTs in a blind retry.mgmt() never retries (1 attempt on 500, 502, 503 and 504) and a lost create answer still creates the project, so a retry hits the same-name 400 or, with a fresh name, a second project. The second half is reasoned from the 400 and was not run.mgmt-api-faults MF01, MF02 (2026-10-10)
Check status as well as present after functionPresent().A 500 on its read returns present: false with status 500 after 1 attempt, which a caller cannot tell from a missing function.mgmt-api-faults MF01 (2026-10-10)

The probes re-run on throwaway projects you create and delete; the calls are the ones the sections make. Sections 3 and 8 additionally need a free-tier project for the free-org rows.

  • Sizing (3) - create a project and re-take the three Nano rejections (create, addon PATCH, available_addons); create with region_selection: {type: "smartGroup", code: "apac"} and read which region lands.
  • Rate budget (4) - burst a cheap scoped read until the 429, reading the budget from the x-ratelimit-* headers; alternate two of your PATs on the same route to re-check the shared counter, and alternate two routes with one token to see the per-route sequences.
  • OAuth (5) - authorize with an unknown client_id, then run the token lifecycle after a real consent: refresh, revoke, re-refresh.
  • Metering (6) - insert a known payload and read pg_database_size(); send a counted batch of REST GETs and watch usage.api-counts catch up; scrape per-project metrics through your gateway with a scoped key.
  • Control-plane faults (2, 8) - point the CLI profile’s api_url, the provider’s endpoint or your client’s base URL at a proxy that answers 500 before or after forwarding, and count the requests each tool sends.
  • Deletions and pauses (8) - delete the project and re-poll the list for the tail; pause a free-tier project and read the data API for the HTTP 540 Project paused.

The measurement harness is public at supabase-lab - one RUNLOG.md per experiment under experiments/ - but its destructive probes run against the author’s orgs and secrets, so a reader re-runs the API calls above and reads the run logs in the repo.

SectionExperiment in supabase-lab, RUNLOG pinned to commit 86dfcf5
1, 5 - the OAuth surfacebyo-oauth
1, 2, 3 - JIT access, templated keys, the replica floor, the backup schedulesfp-platforms
2, 4 - the classic PAT’s reach, the region catalogue, the read-only membership surfaceplatform-facts
1 - JIT grant and invite routes on Pro, scoped tokensjit-db-access, scoped-pats
2, 8 - control-plane faults and the lost-answer createmgmt-api-faults, lifecycle-ops
3, 8 - sizing floors, the legacy door, pause and restoreinstance-sizing
4 - the rate budgetrate-limits
6 - metering and the scoped-key gatewayusage-metering
7 - cross-project trustcross-project-auth
8 - the paused-project sweep, pause and restore timing, the auto-pause check-back and the hibernation ladders2z-wake
ModuleExperimentTestArtifact
F03platform-factsf03-pat-scope.tsnone published
F04cplatform-factsf04-regions.tsnone published
F05platform-factsf05-control-plane-writes.tsnone published
I03instance-sizingi03-legacy-pause-lifecycle.tsnone published
JA01cjit-db-accessja01-jit-lifecycle.tsrun-2026-10-10T01-42-19-583Z, run-2026-10-10T01-51-06-255Z, run-2026-10-10T01-57-55-066Z, run-2026-10-10T02-10-36-037Z, run-2026-10-10T02-41-17-188Z
JA01djit-db-accessja01-jit-lifecycle.tsrun-2026-10-10T01-42-19-583Z, run-2026-10-10T01-51-06-255Z, run-2026-10-10T01-57-55-066Z, run-2026-10-10T02-10-36-037Z, run-2026-10-10T02-41-17-188Z
L01brate-limitsr01-rate-limit-surface.tsnone published
LO04lifecycle-opslo04-duplicate-post.tsrun-2026-10-10T00-43-31-013Z
MF01mgmt-api-faultsmf01-harness-client.tsrun-2026-10-10T07-44-43-736Z
MF02mgmt-api-faultsmf02-harness-create.tsrun-2026-10-10T07-44-43-736Z
MF03mgmt-api-faultsmf03-cli.tsrun-2026-10-10T07-44-43-736Z
MF04mgmt-api-faultsmf04-tofu.tsrun-2026-10-10T07-44-43-736Z
MF05mgmt-api-faultsmf05-post-timeout.tsrun-2026-10-10T07-55-39-410Z
O01cbyo-oautho01-oauth-lifecycle.tsnone published
O01ebyo-oautho01-oauth-lifecycle.tsnone published
S07sfp-platformss07-read-replicas.tsnone published
S07esfp-platformss07-read-replicas.tsnone published
S11sfp-platformss11-backup-schedule.tsnone published
S14sfp-platformss14-secret-jwt-template.tsnone published
S15sfp-platformss15-jit-database-access.tsnone published
SP01scoped-patssp01-creation-surface.tsrun-2026-10-10T07-18-10-870Z, run-2026-10-10T07-19-28-030Z
SP02scoped-patssp02-permission-matrix.tsrun-2026-10-10T07-20-24-545Z
SP04scoped-patssp04-org-scoped-token.tsnone published
SP05scoped-patssp05-sql-read-only.tsrun-2026-10-10T07-20-24-545Z
SP06scoped-patssp06-cli-and-profile.tsrun-2026-10-10T07-19-28-030Z
SP10scoped-patssp10-ratelimit-header-control.tsrun-2026-10-10T07-19-47-655Z
Z01s2z-wakez01-get-surface-wake.tsnone published
Z02s2z-wakez02-write-surface-wake.tsnone published
Z04s2z-wakez04-autopause-wake.tsnone published
If you are askingGo to
Where should a tenant live, and what does it cost?Tenant placement
What does each operation cost in downtime?Platform operation costs
Build the shared tierShared tenancy guide
Move a tenant to its own projectTenant promotion
Merge many projects into oneTenant consolidation
Grant temporary database access with a PATJIT database access
How should clients retry and what survives a restart?Resilience runbook
  1. Supabase, “Supabase for Platforms,” Supabase Docs. https://supabase.com/docs/guides/integrations/supabase-for-platforms (read 2026-11-13; the claim flow and the Nano compute instance sections). ↩ ↩2

  2. Supabase, “Supabase API (v1),” OpenAPI document. https://api.supabase.com/api/v1-json (read 2026-11-13). ↩ ↩2 ↩3 ↩4 ↩5

  3. Supabase, “Personal Access Tokens,” Supabase Docs. https://supabase.com/docs/guides/platform/personal-access-tokens (read 2026-10-07; the sbp_fc prefix sentence re-read 2026-10-10). ↩ ↩2

  4. Supabase Changelog, scoped personal access tokens GA (dated 2026-10-06 in the lab run log). https://supabase.com/changelog/scoped-personal-access-tokens-ga (read 2026-10-10). ↩

  5. Supabase, “apps/studio/data/scoped-access-tokens/scoped-access-token-create-mutation.ts,” supabase/supabase, commit 7ef7d9f. https://github.com/supabase/supabase/blob/7ef7d9f648ae8947adcbeb1ad674b044b68f50dd/apps/studio/data/scoped-access-tokens/scoped-access-token-create-mutation.ts ↩

  6. Supabase, “apps/studio/data/access-tokens/access-tokens-create-mutation.ts,” supabase/supabase, commit 7ef7d9f. https://github.com/supabase/supabase/blob/7ef7d9f648ae8947adcbeb1ad674b044b68f50dd/apps/studio/data/access-tokens/access-tokens-create-mutation.ts ↩

  7. Supabase, “Management API introduction” (rate limits), Supabase Docs. https://supabase.com/docs/reference/api/introduction (read 2026-10-10). ↩

  8. Build a Supabase OAuth integration - the Management API OAuth2 flow (authorize, token exchange, refresh, revoke). ↩

  9. Supabase, “Supabase API (v2),” OpenAPI document. https://api.supabase.com/api/v2-json (read 2026-11-13). ↩