Custom Domains

Custom domains allow you to present a branded experience to your users. Custom domains are available as a add-on for projects on a paid plan. Setting up a custom domain requires Owner or Admin permissions for the project. Currently, you must use a subdomain (e.g., api.example.com, rather than example.com) for the purposes of this guide.

Configure a Custom Domain using the Supabase Dashboard#

Follow the Custom Domains steps in the General Settings page in the Dashboard to set up a custom domain for your project.

Configure a Custom Domain using the Supabase CLI#

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

To get started:

1. Install the Supabase CLI 1.11.3+.
2. Log in to your Supabase account using the CLI.

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:

The output of the create command includes two TXT records[^1] 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:

[^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:

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 (foobarbaz.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). You can initialize a new Supabase client with your custom domain, api.example.com. For example:

  
  

  _10

  import { createClient } from '@supabase/supabase-js'

  _10

  _10

  // Use a custom domain as the supabase URL

  _10

  const supabase = createClient('https://api.example.com', 'public-anon-key')

  
  

• 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:

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:

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.

Vanity Subdomains#

Vanity Subdomains allow you to present a basic branded experience, compared to custom domains. They allow you to host your services at a custom subdomain on Supabase (e.g., my-example-brand.supabase.co) instead of the default, randomly-assigned foobarbaz.supabase.co.

To get started:

1. Install the Supabase CLI 1.22.0+.
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 vanity subdomain for.
4. Ensure that your organization is on a paid plan (Pro/Team/Enterprise plan) in the Billing page of the Dashboard.
5. Ensure that your project has the custom domain add on in the Add ons page of the Dashboard.

Configure a Vanity Subdomain#

This example assumes your Supabase project is foobarbaz with a corresponding API URL foobarbaz.supabase.co and configures a vanity subdomain at my-example-brand.supabase.co.

Check subdomain availability#

Use the check-availability subcommand of the CLI to check if your desired subdomain is available for use:

Activate a subdomain#

Once you've chosen an available subdomain, you can reconfigure your Supabase project to start serving traffic on the vanity subdomain (my-example-brand.supabase.co). The auth service, in particular, will no longer work with the original URL (foobarbaz.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 vanity subdomain:

• any client code (e.g., frontends, mobile apps)
• any OAuth providers (e.g., Google, GitHub)

The activate subcommand can be used to initiate the activation:

Remove a Vanity Subdomain#

If you have a vanity subdomain (my-example-brand.supabase.co) 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:

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

Limitations#

• A Supabase project can—at this time—use either a Custom Domain or a Vanity Subdomain, but not both.
• Some authentication flows like Sign-in with Twitter set cookies to track the progress of the flow. Make sure you use only one domain in your frontend application for this reason. Mixing calls to the Supabase domain foobarbaz.supabase.co and your custom domain could cause those flows to stop working due to the Same Origin Policy enforced on cookies by the browser.