Custom Domains

note

Custom Domains are currently in beta, and are being slowly made available to projects.

Custom domains allow you to present a branded experience to your users. You can also use a subdomain for the purposes of this guide.

To get started:

  1. Install the Supabase CLI 1.11.3+.
  2. Log in to your Supabase account using the CLI.
  3. Ensure that you have Owner or Admin permissions for the project you'd like to set up a custom domain for.
  4. Enable the Custom Domains add-on in the Billing page of the Dashboard.

Configure a Custom Domain#

This example assumes your Supabase project is foobar with a corresponding API URL foobarbaz.supabase.co and configures a custom domain at api.example.com.

Configure a CNAME#

Set up a CNAME record for api.example.com, resolving to foobarbaz.supabase.co., with as low a TTL as possible.

Configure TXT Verification#

Use the create subcommand of the CLI to notify Supabase of your domain and retrieve TXT verification records:

supabase domains create --project-ref foobar --custom-hostname api.example.com --experimental

The output of the create command includes two TXT records1 you will need to set up, in order to verify your control over the domain in question, and for us to issue SSL certificates for it. For example:

[...]
Required outstanding validation records:
        _cf-custom-hostname.api.example.com TXT -> 46BBC14D-D50A-409C-8DB5-F862CF5BA660
        api.example.com TXT -> ca3-F1HvR9i938OgVwpCFwi1jTsbhe1hvT0Ic3efPY3Q

1 One of the records requires you to replace the CNAME record set up in the first step with a TXT record. You'll be able to restore it back to the CNAME after the verification process has been completed.

Verify your domain#

Set up both records as instructed, and then use the reverify command for the Supabase Platform to verify the records:

supabase domains reverify --project-ref foobarbaz --experimental

You might need to wait a few minutes before your updated DNS records are propagated, especially if the older records were using a high TTL.

Activate your domain#

The final activation step reconfigures your project to start serving traffic on your custom domain (api.example.com). The auth service, in particular, will no longer work with the original URL (foobar.supabase.co). As such, it is recommended that you schedule a downtime window of 20-30 minutes, depending on the complexity of your project, to update all the services that need to know about your custom domain:

  • any client code (e.g., frontends, mobile apps)
  • any OAuth providers (e.g., google, github)

Additionally, update the DNS configuration for api.example.com to once more use a CNAME record that resolves to foobarbaz.supabase.co. Finally, you can use the activate subcommand to reconfigure your project:

supabase domains activate --project-ref foobarbaz --experimental

Remove a Custom Domain#

If you have a custom domain (api.example.com) set up for your Supabase project (ref foobarbaz, with assigned endpoints at foobarbaz.supabase.co), and would like to go back to using the Supabase-provisioned endpoints (foobarbaz.supabase.co), you can use the delete subcommand:

supabase domains delete --project-ref foobarbaz --experimental

As with the final activation stage of the process for setting up a custom domain, you'll need to update any references in your client code and OAuth providers from the custom domain to the Supabase-provisioned endpoints.

Limitations#

Edge functions do not honor the custom domain setting and they still have to be invoked via the foobarbaz.supabase.co domain.