Promoting a tenant to its own Supabase project

A tenant on the shared tier starts paying, or needs isolation the shared tier does not offer. This guide moves it onto its own Supabase project - copying its schema and rows - without invalidating the session it already holds.

It assumes you already have a shared tier running: a hub project issuing every tenant’s token, and a shared project separated by RLS on a tenant_id claim that tenant cannot write. That guide covers the trust wiring this one depends on and is the prerequisite for it. Where should a tenant live covers when a tenant is worth promoting at all, and what the dedicated project then costs.

What you will build

• One dedicated project that the tenant moves into, wired to trust the same hub.
• A promotion path that copies the tenant’s rows without invalidating its existing session.
• Optionally, a copy of the tenant’s identity itself, so the dedicated project can issue its own tokens instead of only verifying the hub’s.

Prerequisites: a Personal Access Token in SUPABASE_ACCESS_TOKEN, the service_role key for the shared and dedicated projects, jq, and the shared tier from the guide above already running.

Measurement provenance

Measured 2026-08-03 against live Supabase projects in ap-southeast-1 on Micro compute, Vault 0.3.1, with two tenants and three rows - the same fixture the shared-tenancy guide measures against. Claims marked measured in the evidence table were executed and captured.

Three further runs, all on 2026-08-04, extend that baseline. A client reading its {ref, key} from a discovery endpoint carried a live promotion with zero re-authentication. The identity-migration copy was extended to auth.mfa_factors and to retiring the source identity. And a third rotation run re-read both key sets at every probe for 37 minutes, separating the issuer’s publication lag from the consumer’s cache lag. Timings quoted for those three runs come from the run itself.

Constants

Fact	Value
JWKS refresh	cached in project config; measured: a trusting project did not accept new-key tokens within 20 minutes of a rotation, and honoured a revoked key for 15 - see Rotating the hub’s key

Part 1: promote the tenant to its own project

The tenant is paying. Give it a dedicated project without disturbing its session.

1. Provision and wire it. Create the project, apply the same schema, and register the hub’s JWKS on it, the same way as wiring the trust on the shared project. The schema stays identical, RLS included: the policy is harmless when the table holds one tenant, and identical schemas mean promotion is a data copy rather than a migration.

2. Confirm the token already works there. Before moving any data, the tenant’s existing token should be accepted by the new project and return nothing:

curl -s "https://<dedicated-ref>.supabase.co/rest/v1/items?select=tenant_id" \
  -H "apikey: $DEDICATED_ANON" -H "Authorization: Bearer $TOKEN_A" | jq -c
# []   <- accepted, no rows yet.  PGRST301 here means the JWKS wiring is wrong.

Distinguishing [] from PGRST301 is the whole check. Do it before the copy, while an empty result is still expected.

3. Copy that tenant’s slice. Filtered dump per tenant-scoped table:

for t in items other_table; do
  psql "$SHARED_DB_URL" -c "\copy (select * from public.$t where tenant_id = 'tenant-a') to stdout" \
    | psql "$DEDICATED_DB_URL" -c "\copy public.$t from stdin"
done

Reset sequences afterward, or the first insert on the target collides:

select setval('public.items_id_seq', coalesce((select max(id) from public.items), 1));

Storage objects are not in the database. Copy them separately, per tenant prefix.

Caution

If the shared project uses Vault, its secrets do not survive a copy into a new project. Each project has its own encryption root key, so ciphertext moved by dump or \copy decrypts to ERROR: 22000 ... invalid ciphertext on the target. Read the source key from GET /v1/projects/{ref}/pgsodium and apply it to the target before copying, and do it while the source still exists - after deletion that endpoint returns 400 {"message":"Resource has been removed"}. Full detail in the region migration guide.

4. Repoint. Update your registry so tenant-a resolves to the dedicated ref, and verify with the same unchanged token:

curl -s "https://<dedicated-ref>.supabase.co/rest/v1/items?select=tenant_id,body&order=id" \
  -H "apikey: $DEDICATED_ANON" -H "Authorization: Bearer $TOKEN_A" | jq -c
# [{"tenant_id":"tenant-a","body":"a-row-1"},{"tenant_id":"tenant-a","body":"a-row-2"}]

No re-login, no token reissue, no password reset. The issuer never changed.

5. Reap. The rows stay on the shared instance until you remove them - promotion is not destructive by itself, so keep them through a validation window, then:

delete from public.items where tenant_id = 'tenant-a';

How clients learn where a tenant lives

A tenant’s project ref changes at promotion, and the ref appears in the URL the client calls. Two ways to absorb that:

• A discovery endpoint. The client asks your control plane for its current ref and publishable key, caches the answer, and re-fetches on failure. A config lookup, not a proxy.
• A gateway. Clients hit one stable host and it forwards to the right project, injecting keys, so they never see a ref at all. More moving parts and it sits in the data path.

The token is valid against both projects either way, which removes the hardest thing a gateway would otherwise have to do - it never needs to reissue or rewrite tokens.

Measured 2026-08-04: the discovery endpoint is enough, and the gateway is not needed. A client that read its {ref, publishable key} from a registry at request time followed a tenant through a promotion with zero password logins - the refresh token it already held minted a session at the dedicated project, and the read returned the tenant’s rows there. The other tenant, untouched, still resolved to the shared project and still read its own row, so the flip is per-tenant. The only hosts contacted were the two projects: nothing terminated a request in between.

That leaves ref-hiding as the gateway’s last job, and it is a project setting rather than a component. A vanity subdomain activates over the Management API and gives the tenant a hostname with no project ref in it:

curl -sX POST -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' -d '{"vanity_subdomain":"acme-labs"}' \
  "https://api.supabase.com/v1/projects/$REF/vanity-subdomain/check-availability"
# 201 {"available":true}   <- 201, not 200
curl -sX POST -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' -d '{"vanity_subdomain":"acme-labs"}' \
  "https://api.supabase.com/v1/projects/$REF/vanity-subdomain/activate"

Two things about that call. It wants a bare label, not a hostname - a dotted value is rejected with 400 before availability is evaluated. And the custom domains doc says vanity subdomains are configurable “via the CLI only”; the Management API accepts them directly.

One caveat the same run surfaced: after the move, the shared project keeps serving the tenant’s original token. Promotion is a copy, so both placements answer until the source identity is retired - see below.

Verification

Run these against the same two-tenant fixture immediately after a promotion. Each check confirms that one property of the move survived - the token, the copied rows, the source project’s state - rather than that access was ever denied; the negative controls for that are the build guide’s Verification table, not this one’s.

Check	How	Expected
Token portable	same token against the dedicated project	accepted ([] before copy)
Promotion complete	after the copy, same token, dedicated project	the tenant’s rows
Promotion non-destructive	same token, shared project	rows still present until reaped
Vault survives	select decrypted_secret from vault.decrypted_secrets on the target	plaintext, no invalid ciphertext
Sequences reset	insert on the target	no PK collision

Gotchas and lessons learned

• Identical schemas on both tiers. Promotion becomes a data copy. Keep RLS enabled on dedicated projects even with one tenant - it costs nothing and means the two tiers never diverge.
• Vault does not survive the copy unless you move the encryption root key first, and the source must still exist when you do.

Promotion moves the data, not the identity

A promoted tenant keeps its session, and that is the point of the trust wiring. It does not become independent, and the difference is measurable.

	Measured
Refresh the hub-issued token at the dedicated project	400 refresh_token_not_found - “Invalid Refresh Token: Refresh Token Not Found”
Refresh it at the hub	new access token, still accepted by the dedicated project
Access-token lifetime	3600 s (exp - iat, and the hub’s jwt_exp)
Delete the hub, then read at the dedicated project with a live token	HTTP 200 for the whole observation window; the integration still holds resolved_jwks
Delete the hub, then refresh there	410 Gone, then the host stops resolving

Trust makes the dedicated project a verifier of the hub’s signatures, not an issuer of its own tokens. Verification does not need the hub to exist - the resolved key is held project-side, and a deleted hub’s tokens kept working. Minting does. So the hub is on the availability critical path for every tenant on every project that trusts it, and the blast radius of losing it is one access-token lifetime: an hour on defaults, after which nobody can renew and no dedicated project can recover alone.

Three ways out. Keep the hub on the critical path deliberately and give it the availability that implies; put issuance in a real external IdP so both tiers are verifiers; or move the tenant’s identity into its own project at promotion time. The third one is a runbook rather than an architecture change, so it is the one tested below - and it costs no re-login at all, which was not the expectation going in.

Migrating the identity, so the dedicated project issues its own tokens

Unsupported: nothing in Supabase’s docs sanctions writing into the auth schema. Measured on throwaway projects, and smaller than expected.

Copying one table is enough to break the coupling. With a single auth.users row copied and no third-party-auth integration on the target at all, the tenant logs in at its own project, the token it gets back has iss pointing at that project, app_metadata.tenant_id survives the copy, the RLS read returns its rows, and the project refreshes its own tokens. This is identity migration, not federation; the trust wiring is what carries a tenant until it is promoted, not after.

Carrying the session is why this is a SQL copy rather than POST /auth/v1/admin/users: that endpoint mints a user but cannot carry the refresh token the user is already holding. Moving users between projects sets this against the consolidation direction, which accepts a sign-in and gets the supported endpoint in exchange.

Copying four tables carries the session, not just the identity. Add auth.identities, auth.sessions and auth.refresh_tokens, in that order after auth.users for the foreign keys, and the tenant’s existing refresh token works against the new project. No re-login anywhere.

-- On the target, per table, in FK order: users, identities, sessions, refresh_tokens.
-- `select *` does NOT work - see the generated-column trap below.
do $mig$
declare cols text;
begin
  select string_agg(quote_ident(column_name), ',' order by ordinal_position) into cols
    from information_schema.columns
   where table_schema = 'auth' and table_name = 'users' and is_generated = 'NEVER';
  execute format(
    'insert into auth.users (%s) select %s from json_populate_recordset(null::auth.users, $1::json)',
    cols, cols) using $j$<rows as json from the source>$j$::json;
end $mig$;

-- Then, before the tenant's next refresh:
select setval('auth.refresh_tokens_id_seq',
              (select coalesce(max(id), 1) from auth.refresh_tokens), true);

Three traps, each of which broke a run:

• insert ... select * cannot work. auth.users.confirmed_at and auth.identities.email are GENERATED ALWAYS, and Postgres rejects any non-DEFAULT value for them (428C9). Enumerating columns from the catalog is also what makes the copy tolerant of the two projects running different auth schema versions, which any pair of projects created months apart will.
• The bigserial sequence does not follow the rows. After landing a row with id = 1 the sequence still reported last_value = 1, is_called = false, so the next nextval() hands out an id that already exists. GoTrue rotates the refresh token on every use, so this detonates on the tenant’s first refresh and looks like session porting being unsupported. It is not; it is a missing setval.
• A fresh project 500s for a while after it reports healthy. 500 with SQLSTATE 57P01 on the first call is Postgres restarting inside the settle window, not an answer. Retry before you believe a failure. Measured across five projects on 2026-08-04: create to ACTIVE_HEALTHY took 131-159 s, and all five then refused their first admin/users write with 500 unexpected_failure and accepted the second, one poll later. It is not a race you can get lucky with - budget the retry.
• Do not carry the source’s auth.refresh_tokens.id into a target that has already seen a login. The setval above assumes the target is pristine, which it is for a project provisioned for this promotion. Copy into one that has any prior auth activity and the insert dies on refresh_tokens_pkey instead, because the low ids are taken. Either let the target assign the id (the token string is what the client presents, and the setval then becomes belt-and-braces) or reconcile the ids yourself. Found on 2026-08-04 by running this copy twice against the same pair.

Two of the three unexercised parts were measured on 2026-08-04, on three runs that agreed.

MFA travels. A TOTP factor enrolled and verified on the hub arrives at the target already status: verified when auth.mfa_factors is copied alongside the other four tables, and the same secret produces a code that verifies there for an aal2 session. Without this the zero-re-login result would have quietly excluded every account that had enrolled a factor - the accounts most likely to notice being logged out.

Retiring the source identity is one call, and it closes both doors. After DELETE /auth/v1/admin/users/{id} on the hub, the hub refuses a password grant with invalid_credentials and the previously issued refresh token with refresh_token_not_found, while the dedicated project carries on unaffected. Until you make that call, two projects can issue for the same tenant. What it does NOT do is move the data: the tenant’s rows stay on the shared instance, so reaping them is a separate, deliberate step.

Still not exercised: OAuth and SAML identities. That needs a real external provider, and a lab that fakes one is measuring the fake.

Rotating the hub’s key is a maintenance window

Every project that trusts the hub caches the hub’s key set. That cache is the whole story, and it makes rotation slow in both directions.

Step	Measured
Create a standby signing key	rate limited on a fresh project - Please wait until <ISO8601>, 144 s, 127 s and 131 s across three runs
PATCH standby -> in_use	previous key moves to previously_used automatically
Hub starts issuing new-kid tokens	within 5 s
Trusting project accepts a new-key token	never within 20 minutes - 401 on all 80 polls
Old token after rotation	still accepted
Old token after that key is revoked	still accepted for 15 minutes - 200 on all 60 polls

The mechanism is visible in the API while it happens: the integration’s resolved_at stays frozen at its pre-rotation value with only the old kid in resolved_jwks.

A third run on 2026-08-04, instrumented to re-read both key sets at every probe, separates two lags the first runs could only observe stacked. The hub published the new kid in its own JWKS in about 7 minutes. The trusting project’s cached set held exactly one kid on all 282 probes and never re-resolved at all, across 37 minutes after the rotation. So the window is the consumer’s cache, not the issuer’s publication - which is also the second reason the DELETE + re-POST mitigation cannot work: a consumer forced to re-resolve early would have re-cached a key set that did not yet list the new key. The same run re-read each key’s status immediately before each request, so “revoked but still honoured” is now measured on both sides rather than inferred from a PATCH that returned earlier.

Two consequences, and the second is the one that matters.

New sessions break first. Anyone who signs in or refreshes after the rotation gets a token no trusting project will accept, while everyone holding an older token carries on. That is the opposite of the usual rollout shape, where new code paths fail and old ones keep working - here the fresh credential is the broken one.

Revocation does not revoke. Supabase’s signing-keys documentation says asymmetric revocation “is automatic via the key discovery endpoint”, which is true of the issuing project and false of a third-party consumer inside its cache window. During an incident the hub can rotate and revoke in seconds, and for the next half hour every trusting project will accept the compromised key and reject its replacement.

Caution

The obvious fix does not work. There is no PATCH on the third-party-auth endpoint, so DELETE + re-POST is the only lever - and the re-created integration reported resolved: true while caching the OLD key again, because the hub’s own /auth/v1/.well-known/jwks.json was still advertising only that key minutes after the rotation. Two lags are stacked: the issuer’s JWKS publication and the consumer’s cache. Forcing the consumer to re-resolve buys nothing while the issuer still publishes the old key set.

Plan a hub rotation as a scheduled window with sessions drained, or avoid the hub pattern where key rotation has to be fast. Nothing measured here makes it quick.

What this does not settle

Stated plainly, because the architecture is only partly demonstrated. The routing layer used to head this list and no longer does: it was measured on 2026-08-04, the discovery endpoint carried a promotion with no re-authentication and nothing in the data path, and ref-hiding turned out to be a vanity subdomain rather than a proxy. See the section above.

• The unexercised parts of the identity migration. MFA factors and retiring the source user were measured on 2026-08-04. OAuth and SAML identities were not, and need a real external provider.
• The rotation anomaly. In one of two runs the old token started failing before its key was revoked, while that key was still the only one the trusting project had cached. A third run on 2026-08-04, capturing the JWKS body, the PostgREST error code and each key’s status at every probe, did not reproduce it: the old token returned 200 on all 140 of its probes. That makes the observation unstable rather than explained - one non-reproduction identifies no mechanism - so it stays here.

Evidence

Claim	How it was checked	Result
A promoted tenant can refresh against its own project	Presented the hub’s refresh token to the dedicated project, and to the hub as control	Measured - no. 400 refresh_token_not_found at the dedicated project; the hub issues fine and the result is still accepted there
Verification needs the issuer to be alive	Deleted the hub, then kept reading at the dedicated project with a live token	Measured - no. HTTP 200 for the whole window, resolved_jwks still present, while refresh at the hub went 410 Gone
The cost of losing the hub	Read exp - iat and the hub’s jwt_exp	Measured - 3600 s, so one hour to lockout on defaults
The coupling can be removed by copying auth.users	Copied one row to a project with NO integration configured, then logged in there	Measured - login succeeds, iss is the new project, the claim survives, RLS holds, and it refreshes its own tokens
A rotation on the hub propagates promptly	Rotated to a new ES256 key, then polled a new-key token against the trusting project for 20 minutes	Measured - no. 401 on 80/80 polls, with the integration’s resolved_at frozen pre-rotation
Revoking a key stops trusting projects accepting it	Marked the old key revoked, then polled its token for 15 minutes	Measured - no. 200 on 60/60 polls
Re-creating the integration clears the stale cache	DELETE + re-POST, then polled at 500 ms	Measured - no. Cached the old kid again; the hub’s own JWKS was still advertising only that key
The tenant’s live session can be ported	Copied users, identities, sessions and refresh_tokens in FK order, resynced the sequence, presented the OLD refresh token	Measured - accepted, new token issued by the new project. Zero re-logins
A discovery endpoint carries a promotion without a gateway	Client re-read its {ref, key} from a registry after the flip and continued with the refresh token it already held	Measured - zero password logins, rows read at the dedicated project, the other tenant unaffected, only the two project hosts contacted
Ref-hiding needs no proxy	check-availability then activate on the dedicated project	Measured - both 201, hostname carries no ref. Wants a bare label; the docs say CLI-only, the API accepts it
MFA survives promotion	Enrolled and verified a real TOTP factor, copied auth.mfa_factors, verified the same secret at the target	Measured - factor arrives verified, target session reaches aal2. Three runs
Retiring the source identity closes both issuing paths	DELETE /auth/v1/admin/users/{id} on the hub, then password grant and old refresh token there, and a login at the target	Measured - invalid_credentials and refresh_token_not_found at the hub, target unaffected, the tenant’s rows still on the hub
The rotation window is the consumer’s cache, not the issuer’s	Re-read the hub’s JWKS and the trusting project’s cached set at every probe for 37 minutes	Measured - hub published the new kid in about 7 minutes; the consumer never re-resolved, 282 probes
Create to writable, not just healthy	Timed five projects from create to the first admin/users write that succeeded	Measured - 131-159 s to ACTIVE_HEALTHY; 5 of 5 refused the first write and took the second
Copying auth.refresh_tokens ids into a used target	Ran the copy twice against the same project pair	Measured - refresh_tokens_pkey collision the second time; let the target assign the id
One token validates against two projects	Same unchanged token against both	Measured - accepted by both
Promotion works without re-login	Copied one tenant’s rows, re-read with the same token	Measured - rows returned, no re-auth
Promotion is non-destructive	Re-read the shared project after the copy	Measured - rows still present
Vault survives a transfer but not a copy	Cross-referenced from the transfer lab	Measured - decrypts after transfer, invalid ciphertext after pg_dump

Related

• Running many tenants on one Supabase project
  • the shared tier this guide promotes a tenant off of: the hub, the RLS-scoped schema, and the trust wiring this runbook depends on.
• Migrating a Supabase project to another region
  • the dump-and-restore mechanics behind the promotion copy, including the Vault root-key trap in full.