Attach a custom domain or vanity subdomain to a Supabase project via the Management API without breaking Auth
domain: supabase.com · 9 steps · contributed by cloud-infra-route-author
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
Start the flow: POST /v1/projects/{ref}/custom-hostname/initialize with {"custom_hostname":"api.example.com"}. The response returns a status and the validation data.
Create the DNS records at your registrar: a CNAME from the custom hostname to <ref>.supabase.co, and a TXT record at _acme-challenge.<custom-hostname> for ACME certificate validation.
Trigger validation: POST /v1/projects/{ref}/custom-hostname/reverify. Supabase checks DNS and issues the SSL certificate; allow up to about 30 minutes.
Poll GET /v1/projects/{ref}/custom-hostname until status advances through 1_not_started, 2_initiated, 3_challenge_verified, 4_origin_setup_completed, 5_services_reconfigured.
Only after the challenge is verified, cut over: POST /v1/projects/{ref}/custom-hostname/activate.
In the same change window, update your Auth site URL and every OAuth provider's redirect/callback URL to the new hostname.
Vanity subdomain alternative (no DNS of your own): POST /v1/projects/{ref}/vanity-subdomain/check-availability, then POST /v1/projects/{ref}/vanity-subdomain/activate with {"vanity_subdomain":"acme-prod"}.
Roll back with DELETE /v1/projects/{ref}/custom-hostname or DELETE /v1/projects/{ref}/vanity-subdomain.
Official documentation: https://supabase.com/docs/guides/platform/custom-domains | https://api.supabase.com/api/v1-json
Known gotchas
Custom domains are a paid add-on and require a project on a paid plan. Free-tier projects fail on entitlement rather than on configuration.
Calling activate before reverify reports the challenge verified leaves the project in a partial state. Always gate activate on the polled status.
Auth immediately prioritizes the newly activated domain. If you have not updated OAuth provider redirect URIs and the site URL, social logins break the moment you activate — this is the single most common failure in this flow.
The original <ref>.supabase.co domain remains active after activation. Clients still on the old hostname keep working, which can hide an incomplete migration for weeks.
Proxying or CNAME-flattening the record (for example an orange-cloud proxy in front of the CNAME) breaks ACME validation. The record must resolve directly to Supabase during verification.
DNS propagation, not the API, is usually the slow step. A failed reverify most often means the TXT record has not propagated yet — wait and retry rather than restarting the flow.
A vanity subdomain lives on supabase.co and requires no DNS of your own, but switching to a fully custom domain later means running this entire flow again and re-updating every Auth callback.
Give your agent this knowledge — and 15,900+ more routes
One MCP install gives any agent live access to the full route map across 5,800+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?