How to Connect Supabase to a Custom Domain

Custom domains are available on the Supabase Pro plan ($25/month) and higher. If you are on the Free plan, you need to upgrade before proceeding. Navigate to your project in the Supabase Dashboard, click on the organization settings, and check your current plan. Upgrade if needed — the plan change takes effect immediately.

In the Supabase Dashboard, select your project and go to Project Settings in the left sidebar. Look for the Custom Domains section (it may be under the General or API tab depending on the Dashboard version). Click Add custom domain to begin the setup process. You will be asked to enter the subdomain you want to use — this should be a subdomain like api.yourapp.com or supabase.yourapp.com, not a root domain.

Supabase will provide a CNAME target value that you need to add as a DNS record with your domain registrar or DNS provider. Log into your DNS management panel (Cloudflare, Route53, Namecheap, GoDaddy, etc.) and create a CNAME record. Set the name to your chosen subdomain (e.g., api) and the value to the target Supabase provides. DNS propagation can take up to 48 hours, but typically completes within 15-30 minutes.

1# DNS Record Configuration
2# Type: CNAME
3# Name: api (for api.yourapp.com)
4# Value: <project-ref>.supabase.co  (provided by Supabase)
5# TTL: 3600 (or Auto)
6
7# Example for Cloudflare:
8# Type: CNAME
9# Name: api
10# Target: abcdefghijk.supabase.co
11# Proxy: DNS only (gray cloud) — do NOT proxy through Cloudflare

After creating the DNS record, return to the Supabase Dashboard and click Verify to check the DNS configuration. Supabase will look up your CNAME record and confirm it points to the correct target. Once verified, Supabase automatically provisions an SSL certificate for your custom domain using Let's Encrypt. The SSL certificate is auto-renewed before expiration. The verification and SSL process usually completes within a few minutes.

Once the custom domain is active, update all Supabase client initializations in your application to use the new URL. Replace the default project-ref.supabase.co URL with your custom domain. The anon key and service role key remain the same — only the URL changes. Update all environments (development, staging, production) and any CI/CD configurations that reference the Supabase URL.

1import { createClient } from '@supabase/supabase-js'
2
3// Before: default Supabase URL
4// const supabase = createClient(
5//   'https://abcdefghijk.supabase.co',
6//   'your-anon-key'
7// )
8
9// After: custom domain
10const supabase = createClient(
11  'https://api.yourapp.com',
12  'your-anon-key'  // Same key, no change needed
13)
14
15// Environment variable approach (recommended)
16const supabase = createClient(
17  process.env.NEXT_PUBLIC_SUPABASE_URL!,  // Update this env var
18  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
19)

If you use OAuth providers (Google, GitHub, etc.) or send auth emails (confirmation, password reset), update the redirect URLs to use your custom domain. In the Supabase Dashboard under Authentication > URL Configuration, update the Site URL and redirect URLs. Also update the callback URLs configured in your OAuth provider dashboards (Google Cloud Console, GitHub Developer Settings, etc.) to point to your custom domain.

1# Update in Supabase Dashboard > Authentication > URL Configuration:
2# Site URL: https://yourapp.com
3# Redirect URLs: https://yourapp.com/auth/callback
4
5# Update OAuth callback in provider dashboards:
6# Before: https://abcdefghijk.supabase.co/auth/v1/callback
7# After:  https://api.yourapp.com/auth/v1/callback