> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Custom Domains

Learn how to configure a custom domain for your FusionAuth Cloud instance.

FusionAuth Cloud supports custom domains across all plans. Deployments on Enterprise High Availability plans can enable the Unlimited Custom Domains experience, which includes advanced management capabilities and a modern user interface. In addition to allowing unlimited custom domains, the feature provides the following benefits:

*   The ability to add and remove individual custom domains
*   Custom domain validation and routing with a single DNS change
*   DNS validation status checks for custom domains
*   Faster provisioning of certificates

To enable the custom domains feature on one of your High Availability cloud deployments, open a [support ticket](https://account.fusionauth.io/account/support/).

## Two Interfaces

Customers may use one of two custom domain interfaces. To identify your interface, navigate to the Hosting page, then select Action -> Custom URL(s) for your deployment:

### Custom URL(s)

The Custom Domains page contains a list of domains as in-browser list items, providing the ability to independently add, edit, and delete each domain: ![a list of domains in the browser with the ability to independently add, edit, and delete each domain](https://fusionauth.io/img/docs/cloud/custom-url-issued-with-pending.png)

### Add Custom URL(s) (legacy)

The Custom URL(s) page contains the **Update custom URL(s)** button, which opens the edit page:

![The Update custom URL(s) button, which opens the edit page](https://fusionauth.io/img/docs/cloud/custom-url-update.png)

The Add Custom URL(s) page enables you to modify the entire list of custom domains simultaneously via a text box: ![a text box where you can modify the entire list of custom domains simultaneously](https://fusionauth.io/img/docs/cloud/custom-url-add-domains.png)

To migrate to the modern Custom URL(s) workflow, [open a support ticket](https://account.fusionauth.io/account/support/). This migration requires 30 to 60 minutes of downtime.

## View Existing Custom Domains

### Custom URL(s)

1.  Log in to your account at [account.fusionauth.io](https://account.fusionauth.io/).
    
2.  Navigate to the Hosting page.
    
3.  Select Action -> Custom URL(s) for your deployment.
    
4.  The **Custom Domains** page shows the DNS validation status of each custom domain, and search capabilities.
    
    ![Unlimited custom domains listing.](https://fusionauth.io/img/docs/cloud/ud-list.png)
    
    You can refresh the DNS validation status of a custom domain by selecting Action -> Refresh Status for the domain and clicking the **Refresh** button on the next page.
    

### Add Custom URL(s) (legacy)

1.  Log in to your account at [account.fusionauth.io](https://account.fusionauth.io/).
    
2.  Navigate to Hosting .
    
3.  Select Action -> Add Custom URL(s) for your deployment.
    
4.  The **Add Custom URL(s)** page shows your current list of custom domains.
    
    ![The Update custom URL(s) button, which opens the edit page](https://fusionauth.io/img/docs/cloud/custom-url-update.png)
    

## Add a Domain

> **CAUTION:** Before adding a custom domain, you must create a CNAME record targeting the durable URL for your deployment. Additionally, if your domain has a CAA record, it must allow the Amazon certificate authority to issue certificates for your domain by including at least one of the following domains:
> 
> *   `amazon.com`
> *   `amazontrust.com`
> *   `awstrust.com`
> *   `amazonaws.com`

> **TIP:** The ability to add multiple domains is only available on High Availability (HA) deployments.

### Custom URLs

1.  Log in to your account at [account.fusionauth.io](https://account.fusionauth.io/).
    
2.  Navigate to the Hosting page.
    
3.  Select Action -> Custom URL(s) for your deployment.
    
4.  The **Custom Domains** page shows the DNS validation status of each custom domain, and search capabilities.
    
    ![Unlimited custom domains listing.](https://fusionauth.io/img/docs/cloud/ud-list.png)
    
5.  To add a custom domain to your deployment, click the Add Domain button in the Action menu at the top of the listing page.
    
    ![Action menu button to add a custom domain.](https://fusionauth.io/img/docs/cloud/ud-add-action.png)
    
6.  Enter the new custom domain.
    
7.  Submit the form.
    
8.  You will be redirected back to the custom domain listing page, where you can see the provisioning state and DNS validation status for the new domain.
    
9.  Since the DNS CNAME was created ahead of time, your new custom domain should already be validated and functional. If it has not yet been validated, select Action -> Refresh Status to re-validate the custom domain when DNS changes have propagated.
    

### Add Custom URL(s) (legacy)

> **CAUTION:** The **Add Custom URL(s)** workflow *replaces* the existing configuration. Any domains not included in the form will be deleted.

> **TIP:** Adding the custom domain `auth.piedpiper.com` requires creating two records in your DNS provider:
> 
> *   **A Validation Record CNAME** - authorizes FusionAuth Cloud to use `auth.piedpiper.com`:
>     
>     ```plaintext
>     [random-value].auth.piedpiper.com. CNAME [random-value].acm-validations.aws.
>     ```
>     
> *   **A Vanity URL CNAME** - routes traffic from `https://auth.piedpiper.com` to your FusionAuth deployment, `https://piedpiperdeployment.fusionauth.io`:
>     
>     ```plaintext
>     auth.piedpiper.com CNAME piedpiperdeployment.fusionauth.io
>     ```
>     

1.  Log in to your account at [account.fusionauth.io](https://account.fusionauth.io/).
2.  Navigate to Hosting .
3.  Select Action -> Add Custom URL(s) for your deployment.
4.  The **Add Custom URL(s)** page shows your current list of custom domains.
5.  Add the domain names to **Custom domains** field; for example, `auth.piedpiper.com`. Note that the contents of this field will *replace* all existing domains.
6.  Confirm you want the change by entering the text `CONFIRM` in the **Confirm** text field.
7.  Click Submit .
8.  You'll be sent to a verification screen, which will update as FusionAuth Cloud creates your DNS records.
9.  Wait a few minutes. Once complete, you should see a set of records; **you must add these records to your DNS**.
10.  Once validated, the status will move to `Issued`. No further action is required at this point.

> **NOTE:** A custom domain added in the account management portal will still work properly without refreshing the status as long as the DNS CNAME record exists. The validation indicators and status refresh are meant to provide additional feedback for configuring and troubleshooting a new custom domain.

## Delete a Domain

### Custom URL(s)

1.  Log into your account at [account.fusionauth.io](https://account.fusionauth.io/).
2.  If your deployment contains a custom domain that is no longer in use, you can remove it by selecting Delete in the Action menu for the domain.
3.  Confirm that the domain you want to delete is shown on the page, enter `DELETE` in the form field to confirm the operation, and submit the form.
4.  You will be redirected back to the custom domain listing page, which continues to display the deleted domain with the `Destroying` status while FusionAuth Cloud cleans up the supporting infrastructure.
    
    > **NOTE:** The deleted custom domain will continue to operate normally until the certificate for that domain expires. To prevent traffic for that custom domain being routed to your FusionAuth deployment, remove the DNS CNAME record that was created when adding the domain.
    

### Add Custom URL(s) (legacy)

> **CAUTION:** The **Add Custom URL(s)** workflow *replaces* the existing configuration. Any domains not included in the form will be deleted.

1.  Log in to your account at [account.fusionauth.io](https://account.fusionauth.io/).
2.  Navigate to Hosting .
3.  Select Action -> Add Custom URL(s) for your deployment.
4.  The **Add Custom URL(s)** page shows your current list of custom domains.
5.  Remove the domain name from the **Custom domains** field; for example, `auth.piedpiper.com`. Note that the contents of this field will *replace* all existing domains.
6.  Confirm you want the change by entering the text `CONFIRM` in the **Confirm** text field.
7.  Click Submit .
8.  You'll be sent to a verification screen, which will update as FusionAuth Cloud creates your DNS records.
9.  Wait a few minutes. Once complete, you should see a set of records; **you must update your DNS with these records**.
10.  Once validated, the status will move to `Issued`. No further action is required at this point.

## Durable FusionAuth CNAME

If you have an existing custom domain, you might have an existing vanity URL with a CNAME similar to this:

```plaintext
auth.piedpiper.com CNAME piedpiper-deployment-prod.fusionauth.io
```

You may notice FusionAuth Cloud now supports a `[uuid].durable.fusionauth.io` CNAME where `[uuid]` is a UUID such as `3ffe6da1-e6f5-4be4-96e0-5dabdf42fd68`. For instance:

```plaintext
auth.piedpiper.com CNAME [uuid].durable.fusionauth.io
```

This durable URL will not change and is functionally equivalent to the above vanity URL. Using this updated CNAME will enable use of [Disaster Recovery services](https://fusionauth.io/docs/cloud/reference/disaster-recovery.md) should you require them at a later point.

## Unlimited Domains Transition (Enterprise High Availability Only)

When unlimited domains are first enabled for a deployment, that deployment enters a transition state that lasts **30 to 60 minutes**.

This allows time to perform any necessary DNS changes for existing custom domains to prevent domain resolution errors when completing the cutover to Unlimited Custom Domains. During this transition, other deployment actions such as upgrading or destroying the deployment are unavailable, but your deployment will continue to serve traffic normally.

You need to update existing custom domain DNS records pointing to the deployment's `*.fusionauth.io` domain name to refer to the [Durable FusionAuth CNAME](#durable-fusionauth-cname). Once you have updated the DNS records, you can complete the cutover to Unlimited Custom Domains from the account management portal by selecting Cutover Custom URL(s) from the Action menu at the top of the custom domains listing page and completing the form on the next page. If a deployment does not have any existing custom domains when unlimited domains are enabled, it can be cut over immediately.