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) -> the control plane.
- Control plane (provisioning service, tenant->ref map, usage poller, rate-budgeted client) -> the credential-proxy gateway, and ->
api.supabase.com/v1directly if the scale is small. - Credential-proxy gateway (optional: the PAT stays server-side, scoped keys go out) ->
api.supabase.com/v1. api.supabase.com/v1(projects / config / addons / analytics) -> the tenant pool: one project per tenant, or a shared tier.
1. Decide who owns the project
Section titled “1. Decide who owns the project”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.
Scoped personal access tokens
Section titled “Scoped personal access tokens”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
/v1API. The public/v1OpenAPI 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 withPOST /platform/profile/scoped-access-tokens5 and classic tokens withPOST /platform/profile/access-tokens,6 both outside/v1. The classic-token route,GET /platform/profile/access-tokens, answers a PAT401 {"message":"Unsupported access token"}, whileGET /v1/profile/access-tokensandGET /v1/access-tokensanswer404andGET /v1/organizationsanswers200. Only GET was sent, the scoped-token route was not probed, and no token was minted. - The lab token has the
sbp_fcformat; which scope it was created with was not read. With it,GET /v1/profileanswers403 {"message":"This endpoint requires a user-scoped access token"}, and the Supabase CLI 2.120.0 exits 1 onsupabase whoami(unexpected get profile status 403) whilesupabase orgs listandsupabase projects listexit 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 1answers201on both/database/queryand/database/query/read-only;create tablethrough the read-only route is refused with400andERROR: 25006: cannot execute CREATE TABLE in a read-only transactionand the table is absent on read-back, while/database/queryanswers201and 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).
2. Provision a tenant
Section titled “2. Provision a tenant”One call creates a project; the rest is setup around it.
POST /v1/projectswithorganization_slug, a strong generateddb_pass, and a region. Create ->ACTIVE_HEALTHYmeasured 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 pickedap-northeast-2. Defer the city choice instead of pinning per tenant. - Fresh projects refuse their first
/auth/v1/admin/userswrite after reportingACTIVE_HEALTHY: 5 of 5 with500 unexpected_failure, accepting the second call one poll later (2026-08-04), and 2 of 2 with500 "Database error checking email"for ~10 s after passing the per-service health poll (2026-08-03). PollGET /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=trueand select bynameORtype- new projects carry both legacy JWTs and the newsb_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/projectswhose answer was lost to a 1 s client cap (LO04), to a 4 s client timeout over an 8 s hold, or replaced by a500after upstream created the project (MF02) left 1 project with that name in each case. An identical re-send answers400 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-name400is 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.
3. Know the sizing floors
Section titled “3. Know the sizing floors”| Org class | Nano | Floor | Pause |
|---|---|---|---|
| Paid (Pro) org | rejected three ways: create 400 Minimum instance size on paid plans is Micro, addon PATCH 400 addon_variant: Invalid input, absent from available_addons | Micro, always-on | 400 Project is not free-tier |
| Free org | accepted (201) - and there is NO compute addon catalogue at all | shared/free compute | full 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 org | n/a | keeps its paused state after the upgrade | one-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.
4. Budget the rate limit
Section titled “4. Budget the rate limit”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 withretry-after: 60and 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’sx-ratelimit-remainingdrops 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-remainingis 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;SP10agrees with the documented scope. Whether the header separates two tokens of one user on a given route was not re-measured inSP10, which used one token.
At fleet scale, build the client as a queue with a token bucket.
5. Let users bring their own backend
Section titled “5. Let users bring their own backend”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_idat/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-bearertoken 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.
6. Meter what tenants consume
Section titled “6. Meter what tenants consume”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.
- 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.
- 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. - 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.
8. Gotchas and lessons learned
Section titled “8. Gotchas and lessons learned”- 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 pausedright after a manual pause on a free org, but two free-plan projects that auto-paused answered NXDOMAIN on independent public resolvers, withdb.<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 /pausereachedINACTIVEin 62 s throughPAUSING, andPOST /restorereachedACTIVE_HEALTHYin 181 s throughCOMING_UPandRESTORING. - Four project-scoped reads answer
200with 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-keysreturned[],GET /advisors/performanceandGET /advisors/securityreturned{"lints":[]}andGET /config/database/poolerreturned[], 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
statusandcreated_atand no pause time, the organization listing addsinserted_at, and/actionslists 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}/postgrestcarriesjwt_secretin its response schema,GET /v1/projects/{ref}/api-keyscarriesapi_keyand takes arevealparameter, and both name a secret-read permission (data_api_config_secret_read,api_gateway_keys_secret_read) inx-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
INACTIVEat 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_hibernatinginvalidation_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.
Control-plane fault behaviour
Section titled “Control-plane fault behaviour”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.
| Client | Reads (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 thrown | no retry; the caller gets the 500 | throws 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 attempt | n/a | n/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 each | 60 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 retried | a 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
500after upstream created the project leaves the provider’s state empty and an orphan upstream. The plain re-apply sends 1 POST and gets400(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 createanswered500after upstream created it exits 1 with 1 project carrying the name (MF03).tofu importof the orphan was not run. - Partial applies converge as follows (
MF04, one trial each). A settings write answered500before upstream leaves the project in state and the settings not: the next plan exits 2. A settings write that landed upstream but answered500converges: the next plan exits 0 with no pending change. A DELETE that landed but answered500leaves a state entry that the next destroy removes cleanly, because the GET and DELETE both answer404and the provider accepts that. - No tool duplicated a POST in any trial (
MF05); the same-name400is 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).
Verified / tested
Section titled “Verified / tested”| Claim | How it was checked |
|---|---|
| Create -> healthy 131-159 s paid / 12-13 s free | Measured 2026-08-17/18, n=5+ on paid |
Smart region accepted on a paid org, picked ap-northeast-2 | Measured 2026-08-17 |
| Nano rejected three ways on paid, accepted (201) on free | Measured 2026-08-17/18 |
| Legacy project: paused survives upgrade, cannot re-pause | Measured 2026-08-18 - 400 Project is not free-tier |
Rate-limit headers + JSON 429 with retry-after: 60 | Measured 2026-08-17 - burst to the boundary |
| OAuth authorize: 422 client validation first | Measured 2026-08-17 |
Project IdP: client_id claim usable in RLS | Measured 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 API | Measured 2026-08-17/18 |
| Scoped-key gateway: 200/278 families, 403 deny-by-default, ~1 s audit | Measured 2026-08-18 against a live credential-proxy deployment |
| Refresh only at the issuing project | Measured 2026-08-18 - 400 refresh_token_not_found verbatim |
| Parked: 52 GETs, zero wakers | Measured 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 200 | Measured 2026-10-13 - Z01, one run, with a seeded security-advisor finding |
| Pause 62 s, restore 181 s | Measured 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-ups | Measured 2026-09-09 on a free-plan nano project, 4 rungs of 8 |
| Free-plan projects auto-pause, including an untouched control | Read 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 token | Measured 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 token | Measured 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 it | Measured 2026-10-10 - SP05, the control for a read-only scoped token |
x-ratelimit-remaining is a per-route counter at limit 120 | Measured 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 route | Measured 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 retries | Measured 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 name | Measured 2026-10-10 - LO04 n=1 and MF02; a fresh-name retry not run |
What to do about it
Section titled “What to do about it”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.
| Practice | Evidence | Module |
|---|---|---|
| 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) |
Verification
Section titled “Verification”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 withregion_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 watchusage.api-countscatch 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’sendpointor 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.
File reference
Section titled “File reference”| Section | Experiment in supabase-lab, RUNLOG pinned to commit 86dfcf5 |
|---|---|
| 1, 5 - the OAuth surface | byo-oauth |
| 1, 2, 3 - JIT access, templated keys, the replica floor, the backup schedule | sfp-platforms |
| 2, 4 - the classic PAT’s reach, the region catalogue, the read-only membership surface | platform-facts |
| 1 - JIT grant and invite routes on Pro, scoped tokens | jit-db-access, scoped-pats |
| 2, 8 - control-plane faults and the lost-answer create | mgmt-api-faults, lifecycle-ops |
| 3, 8 - sizing floors, the legacy door, pause and restore | instance-sizing |
| 4 - the rate budget | rate-limits |
| 6 - metering and the scoped-key gateway | usage-metering |
| 7 - cross-project trust | cross-project-auth |
| 8 - the paused-project sweep, pause and restore timing, the auto-pause check-back and the hibernation ladder | s2z-wake |
Modules
Section titled “Modules”Related
Section titled “Related”| If you are asking | Go 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 tier | Shared tenancy guide |
| Move a tenant to its own project | Tenant promotion |
| Merge many projects into one | Tenant consolidation |
| Grant temporary database access with a PAT | JIT database access |
| How should clients retry and what survives a restart? | Resilience runbook |
References
Section titled “References”-
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
-
Supabase, “Supabase API (v1),” OpenAPI document. https://api.supabase.com/api/v1-json (read 2026-11-13). ↩ ↩2 ↩3 ↩4 ↩5
-
Supabase, “Personal Access Tokens,” Supabase Docs. https://supabase.com/docs/guides/platform/personal-access-tokens (read 2026-10-07; the
sbp_fcprefix sentence re-read 2026-10-10). ↩ ↩2 -
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). ↩
-
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 ↩
-
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 ↩
-
Supabase, “Management API introduction” (rate limits), Supabase Docs. https://supabase.com/docs/reference/api/introduction (read 2026-10-10). ↩
-
Build a Supabase OAuth integration - the Management API OAuth2 flow (authorize, token exchange, refresh, revoke). ↩
-
Supabase, “Supabase API (v2),” OpenAPI document. https://api.supabase.com/api/v2-json (read 2026-11-13). ↩
Linked from
- Auditing Supabase: where each copy of an event lives, and who can erase it
- Per-project cost attribution on Supabase
- Query Supabase project logs through the Management API after logs.all
- Supabase compute and disk sizing
- Temporary token-based database access (JIT): grants, expiry and what gets logged
- What a Supabase platform operation costs a client