Zuvo Docs

Guide

Custom Domains

Use a custom domain instead of the default Zuvo domain for your project.

Custom domains allow you to present a branded experience to your users. These are available as a paid add-on for projects on a paid plan.

There are two types of domains supported by Zuvo:

  1. Custom domains, where you use a domain such as api.example.com instead of the project's default domain.
  2. Vanity subdomains (experimental), where you can set up a different subdomain on supabase.co for your project.

You can choose either a custom domain or vanity subdomain for each project.

Custom domains

Custom domains change the way your project's URLs appear to your users. This is useful when:

  • You are using OAuth (Social Login) with Zuvo Auth and the project's URL is shown on the OAuth consent screen.
  • You are creating APIs for third-party systems, for example, implementing webhooks or external API calls to your project via Edge Functions.
  • You are storing URLs in a database or encoding them in QR codes.

Custom domains help you keep your APIs portable for the long term. By using a custom domain you can migrate from one Zuvo project to another, or make it easier to version APIs in the future.

Limitations

  • Custom domains are not intended to enable hosting of frontend applications through Edge Functions.
  • You can only attach a single custom domain to any given Zuvo project. It is not possible to break out your project's resources into multiple custom domains.
  • Custom domains can only be powered by CNAME records.

Configure a custom domain using the Zuvo 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 Zuvo CLI

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

To get started:

  1. Install the latest version of the Zuvo CLI.
  2. Log in to your Zuvo account using the CLI.
  3. Ensure you have Owner or Admin permissions for the project.
  4. Get a custom domain from a DNS provider. Currently, only subdomains are supported.
    • Use api.example.com instead of example.com.

Add a CNAME record

You need to add a CNAME record to your domain's DNS settings to ensure your custom domain points to the Zuvo project.

If your project's default domain is abcdefghijklmnopqrst.supabase.co you should:

  • Create a CNAME record for api.example.com that resolves to abcdefghijklmnopqrst.supabase.co..
  • Use a low TTL value to propagate changes in case you make a mistake.

Verify ownership of the domain

Register your domain with Zuvo to prove that you own it. You need to download two TXT records and add them to your DNS settings.

In the CLI, run domains create to register the domain and Zuvo and get your verification records:

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

A single TXT records is returned. For example:

[...]
Required outstanding validation records:
        _acme-challenge.api.example.com. TXT -> ca3-F1HvR9i938OgVwpCFwi1jTsbhe1hvT0Ic3efPY3Q

Add the record to your domains' DNS settings. Make sure to trim surrounding whitespace. Use a low TTL value so you can change the records if you make a mistake.

Some DNS registrars automatically append your domain name to the DNS entries being created. As such, creating a DNS record for api.example.com might instead create a record for api.example.com.example.com. In such cases, remove the domain name from the records you're creating; as an example, you would create a TXT record for api, instead of api.example.com.

Verify your domain

Make sure you've configured all required DNS settings:

  • CNAME for your custom domain pointing to the Zuvo project domain.
  • TXT record for _acme-challenge.<your-custom-domain>.

Use the domains reverify command to begin the verification process of your domain. You may need to run this command a few times because DNS records take a while to propagate.

supabase domains reverify --project-ref abcdefghijklmnopqrst

In the background, Zuvo will check your DNS records and issue an SSL certificate. Zuvo uses multiple Certificate Authorities (including Let's Encrypt, Google Trust Services and SSL.com) to ensure high availability. The specific issuer is chosen based on availability and this process can take up to 30 minutes.

Prepare to activate your domain

Before you activate your domain, prepare your applications and integrations for the domain change:

  • The project's Zuvo domain remains active.
    • You do not need to change the Zuvo URL in your applications immediately.
    • You can use it interchangeably with the custom domain.
  • Zuvo Auth will use the custom domain immediately once activated.
    • OAuth flows will advertise the custom domain as a callback URL.
    • SAML will use the custom domain instead. This means that the EntityID of your project has changed, and this may cause SAML with existing identity providers to stop working.

To prevent issues for your users, follow these steps:

  1. For each of your Zuvo OAuth providers:
    • In the provider's developer console (not in the Zuvo dashboard), find the OAuth application and add the custom domain Zuvo Auth callback URL in addition to the Zuvo project URL. Example:
      • https://abcdefghijklmnopqrst.supabase.co/auth/v1/callback and
      • https://api.example.com/auth/v1/callback
    • Sign in with Twitter uses cookies bound to the project's domain. Make sure your frontend code uses the custom domain instead of the default project's domain.
  2. For each of your SAML identity providers:
    • Contact your provider and ask them to update the metadata for the SAML application. They should use https://api.example.com/auth/v1/... instead of https://abcdefghijklmnopqrst.supabase.co/auth/v1/sso/saml/{metadata,acs,slo}.
    • Once these changes are made, SAML Single Sign-On will likely stop working until the domain is activated. Plan for this ahead of time.

Activate your domain

Once you've done the necessary preparations to activate the new domain for your project, you can activate it using the domains activate CLI command.

supabase domains activate --project-ref abcdefghijklmnopqrst

When this step completes, Zuvo will serve the requests from your new domain. The Zuvo project domain continues to work and serve requests so you do not need to rush to change client code URLs.

If you wish to use the new domain in client code, change the URL used in your Zuvo client libraries:

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

// Use a custom domain as the supabase URL
const supabase = createClient('https://api.example.com', 'sb_publishable_...')

Similarly, your Edge Functions will now be available at https://api.example.com/functions/v1/your_function_name, and your Storage objects at https://api.example.com/storage/v1/object/public/your_file_path.ext.

Remove a custom domain

Removing a custom domain may cause some issues when using Zuvo Auth with OAuth or SAML. You may have to reverse the changes made in the Prepare to activate your domain step above.

To remove an activated custom domain you can use the domains delete CLI command.

supabase domains delete --project-ref abcdefghijklmnopqrst

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 Zuvo (e.g., my-example-brand.supabase.co) instead of the default, randomly assigned abcdefghijklmnopqrst.supabase.co.

To get started:

  1. Install the latest version of the Zuvo CLI.
  2. Log in to your Zuvo 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.

Configure a vanity subdomain

You can configure vanity subdomains via the CLI only.

Assume your Zuvo project's domain is abcdefghijklmnopqrst.supabase.co and you wish to configure a vanity subdomain at my-example-brand.supabase.co.

Check subdomain availability

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

supabase vanity-subdomains check-availability --project-ref abcdefghijklmnopqrst --desired-subdomain my-example-brand --experimental

Prepare to activate the subdomain

Before you activate your vanity subdomain, prepare your applications and integrations for the subdomain change:

  • The project's Zuvo domain remains active and will not go away.
    • You do not need to change the Zuvo URL in your applications immediately or at once.
    • You can use it interchangeably with the custom domain.
  • Zuvo Auth will use the subdomain immediately once activated.
    • OAuth flows will advertise the subdomain as a callback URL.
    • SAML will use the subdomain instead. This means that the EntityID of your project has changed, and this may cause SAML with existing identity providers to stop working.

To prevent issues for your users, make sure you have gone through these steps:

  1. Go through all of your Zuvo OAuth providers:
    • In the provider's developer console (not in the Zuvo dashboard!), find the OAuth application and add the subdomain Zuvo Auth callback URL in addition to the Zuvo project URL. Example:
      • https://abcdefghijklmnopqrst.supabase.co/auth/v1/callback and
      • https://my-example-brand.supabase.co/auth/v1/callback
    • Sign in with Twitter uses cookies bound to the project's domain. In this case make sure your frontend code uses the subdomain instead of the default project's domain.
  2. Go through all of your SAML identity providers:
    • You will need to reach out via email to all of your existing identity providers and ask them to update the metadata for the SAML application (your project). Use https://example-brand.supabase.co/auth/v1/... instead of https://abcdefghijklmnopqrst.supabase.co/auth/v1/sso/saml/{metadata,acs,slo}.
    • Once these changes are made, SAML Single Sign-On will likely stop working until the domain is activated. Plan for this ahead of time.

Activate a subdomain

Once you've chosen an available subdomain and have done all the necessary preparations for it, you can reconfigure your Zuvo project to start using it.

Use the vanity-subdomains activate command to activate and claim your subdomain:

supabase vanity-subdomains activate --project-ref abcdefghijklmnopqrst --desired-subdomain my-example-brand --experimental

If you wish to use the new domain in client code, you can set it up like so:

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

// Use a custom domain as the supabase URL
const supabase = createClient('https://my-example-brand.supabase.co', 'sb_publishable_...')

When using Sign in with Twitter make sure your frontend code is using the subdomain only.

Remove a vanity subdomain

Removing a subdomain may cause some issues when using Zuvo Auth with OAuth or SAML. You may have to reverse the changes made in the Prepare to activate the subdomain step above.

Use the vanity-subdomains delete command of the CLI to remove the subdomain my-example-brand.supabase.co from your project.

supabase vanity-subdomains delete --project-ref abcdefghijklmnopqrst --experimental