Custom domains

A custom domain lets your app call https://api.example.com instead of https://app-one.acme.supahost.space. It looks better in OAuth consent screens and email links, and it means you can move hosting later without changing URLs in shipped mobile apps. HTTPS certificates come from Let's Encrypt and are issued and renewed for you.

Builder includes 1 custom domain, Pro 3 and Business 10, shared across the instance's projects. Each extra domain is $2 a month.

Add a domain

1. Open Dashboard → your project → Domains and add the hostname, for example api.example.com.
2. The page shows the DNS record to create. Add it at your DNS provider (see below).
3. Wait. SupaHost checks DNS about once a minute. When the record is right, it requests a certificate, and the domain becomes active once HTTPS answers.

A hostname can belong to only one SupaHost project. Hostnames under supahost.space and supahost.app are rejected.

DNS records

You have two choices. A CNAME is the simpler one.

Subdomain (recommended): a CNAME from your subdomain to the project host.

A records: point the name at your instance's IP address. You can look it up with dig +short acme.supahost.space. If there are several A records for the name, all of them must equal the instance IP.

Root domain (example.com with no subdomain): the record label is @. Plain DNS doesn't allow a CNAME at the root, so you need a provider that supports ALIAS, ANAME or CNAME flattening, or use an A record.

You can check what the world sees before waiting on SupaHost:

dig +short CNAME api.example.com
# app-one.acme.supahost.space.

Cloudflare: use "DNS only"

On Cloudflare the record must be set to DNS only (grey cloud), not Proxied (orange cloud). When proxied, Cloudflare answers DNS with its own IPs and terminates HTTPS itself, so the DNS check fails and Let's Encrypt can't issue a certificate for your instance. See Custom domain behind Cloudflare proxy.

Domain states

DNS is checked on every pass, roughly each minute, for 14 days after you add the domain. If it hasn't verified by then, checks stop; fix the record, then remove the domain and add it again. Stuck? See Custom domain stuck verifying.

To test an active domain:

curl -H "apikey: $SUPABASE_ANON_KEY" https://api.example.com/auth/v1/health

What changes when a domain goes active

When a project has an active custom domain, the oldest active one becomes the project's public address for Auth and functions:

• Auth uses it as its external URL, so links in Auth emails and the OAuth callback URL use your domain: https://api.example.com/auth/v1/callback.
• Studio uses it as the project URL.
• Edge Functions see it in SUPABASE_URL.

Some things stay on the SupaHost host:

• The iss claim in user JWTs stays https://app-one.acme.supahost.space/auth/v1.
• Public Storage URLs keep using the SupaHost host.

Your app can use either address. Point your client at the new one:

const supabase = createClient('https://api.example.com', process.env.SUPABASE_ANON_KEY!)

Update OAuth providers

This is the step people miss. After the domain goes active, OAuth providers redirect to the new callback URL, so each provider's app settings must allow it. In Google Cloud Console, GitHub, Apple and the rest, add https://api.example.com/auth/v1/callback as an authorised redirect or callback URL. The Auth tab shows the current callback URL for each provider.

If sign-in breaks with a "redirect_uri mismatch" error right after a domain goes live, this is why. See OAuth broke after adding a custom domain and Social login (OAuth).

Your own app's URLs (Site URL and Redirect URLs on the Auth tab) don't change; those are where users land after sign-in, not the Auth server's address. See Site URL and redirect URLs.

Related

• Projects
• Plans and limits
• Security at SupaHost