> For the complete documentation index, see [llms.txt](https://docs.diaflow.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.diaflow.io/workspace/custom-domain.md).

# Custom domain

Use a custom domain to give your workspace a branded web address.

Once setup is complete, your team can sign in and use Diaflow from that address.

The workspace owner can:

* Set up a new custom domain
* View custom domain information
* Remove custom domain

{% hint style="info" %}
Only the **workspace owner** can manage the custom domain.
{% endhint %}

{% hint style="warning" %}
**Don't confuse this with the "Domains" section above it.** On the Organization settings page, **Domains** controls which *email domains* can request to join your organization (e.g. so only `@yourcompany.com` emails can request access). **Custom domain**, further down the same page, is what gives your workspace its own branded URL (e.g. `app.yourcompany.com`). The two are unrelated — you don't need to set up one to use the other.
{% endhint %}

## Set up a new custom domain

Open **Workspace settings > Organization** and scroll to the **Custom domain** section. Click **Set up a Custom Domain**.

<figure><img src="/files/xwIgF3W7Qb1J4UPCQq7V" alt=""><figcaption></figcaption></figure>

> Organization settings page, scrolled to the **Custom domain** section, with the **Set up a Custom Domain** button highlighted.

{% hint style="warning" %}
If you close this wizard before finishing all 4 steps, Diaflow will warn you: *"Are you sure you want to exit? If you close this popup now, the custom domain setup will be lost and you'll need to start over."* Make sure you have time to finish (or at least reach Step 3) before starting.
{% endhint %}

### Step 1: Verify domain ownership

1. Enter the domain or subdomain you want to connect to your workspace.
2. Click **Continue**.

Example: `app.yourcompany.com`

{% hint style="info" %}
You must own the domain, or have permission to create a subdomain on it.
{% endhint %}

<figure><img src="/files/78KKz3csKREtivIN1wpJ" alt=""><figcaption></figcaption></figure>

> Step 1 modal, showing the "What domain or subdomain would you like to connect to your workspace?" input field with an example typed in.

### Step 2: Verify domain ownership

This step confirms you actually own the domain before Diaflow lets you use it.

1. Click **Read our setup guide**. This opens a step-by-step guide **in a new tab**, automatically generated for your specific domain and DNS provider (Diaflow detects it; the examples below show Cloudflare, but the guide adapts to whichever provider your domain uses).
2. In that guide, follow the numbered steps to log into your DNS provider and add a **TXT record** with the exact values Diaflow gives you:
   * **Type:** `TXT`
   * **Host / Name:** usually `@` (root domain). Copy the exact value shown in your guide
   * **Value:** a unique `verification_token=...` string - copy it exactly, don't retype it
3. Save the record at your DNS provider.
4. Return to the Diaflow tab and click **Start verification**.

<figure><img src="/files/6ywL5j4STj9qL8AlTe1O" alt=""><figcaption></figcaption></figure>

> The auto-generated setup guide page, showing the TXT record values with their copy-icon buttons.

While Diaflow checks for the record, the button shows **"Verifying your domain"** (pending). This is usually quick, but DNS changes can take a few minutes to propagate. If it's taking a while, a **Restart verification process** button appears so you can re-check.

Once detected, it turns into a green **"Verification is complete"** confirmation, and **Continue** becomes clickable.

📸 **Screenshot suggestion (3 images, shown in sequence):** Since this step involves switching between two different apps, which is the #1 place no-code users get lost, show it as a short numbered sequence instead of one screenshot:

<figure><img src="/files/s9f4CmtukNmRDEVhidys" alt=""><figcaption></figcaption></figure>

> The TXT record filled in at the DNS provider, right before saving.

<figure><img src="/files/MyukacEMdqVPoDliDvvm" alt=""><figcaption></figcaption></figure>

> Back in Diaflow, the button showing **"Verifying your domain"** (pending, yellow).

<figure><img src="/files/2iDaptrfEb0xZuj07bsm" alt=""><figcaption></figcaption></figure>

> The button showing the green **"Verification is complete"** state.

### Step 3: Configure your DNS

Diaflow generates **two CNAME records** for you to add at your DNS provider:

| Type  | Name                                          | Target                                                        | Purpose                                                       |
| ----- | --------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
| CNAME | a long auto-generated string + your subdomain | a long auto-generated string ending in `.acm-validations.aws` | SSL certificate validation (so your custom domain gets HTTPS) |
| CNAME | your subdomain (e.g. `app`)                   | a target address provided by Diaflow                          | Routes your custom domain to your Diaflow workspace           |

Both values have a copy-icon next to them. Always use **copy**, don't retype, since these strings are long and case-sensitive.

{% hint style="info" %}
Right after you reach this step, Diaflow shows a **"Generating a SSL Certificate and records for your custom domain"** loading message for a moment before the table above appears. That's normal, just wait for it.
{% endhint %}

{% hint style="danger" %}
**If your DNS provider is Cloudflare (or any provider with a "proxy" feature):** set both CNAME records to **DNS only** (grey cloud), **not** "Proxied" (orange cloud). Cloudflare defaults new records to Proxied. If you leave that on, domain verification and SSL activation will fail or get stuck.
{% endhint %}

1. Go to your DNS provider and add both CNAME records exactly as shown (Type, Name, Target).
2. Make sure proxy/CDN settings are off for both, if your provider has that option.
3. Return to Diaflow and click **Continue**.

<figure><img src="/files/WjIMdRE7r8UrlD1zgacN" alt=""><figcaption></figcaption></figure>

> Step 3 table with the two CNAME records.

<figure><img src="/files/2GHcfzfvq4OkpVEjAZCB" alt=""><figcaption></figcaption></figure>

> The "Add record" dialog with Proxy status still set to **"Proxied"** (orange cloud).

<figure><img src="/files/X106lgAdrkeQpgvjotfm" alt=""><figcaption></figcaption></figure>

> The same dialog with Proxy status switched to **"DNS only"** (grey cloud), ready to save.

### Step 4: Wait for activation

Diaflow now checks your DNS and issues an SSL certificate for your domain.

* You'll see **"Activating your domain"**. This can take up to 30 minutes. You can safely click **Close this window** and come back later; Diaflow keeps checking in the background.
* When it's done, you'll see **"Custom domain activated."** The message confirms you can now access your workspace via your custom domain.

<figure><img src="/files/cWIrE0FQEHCJqVGdK9kc" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/vntqL0W2QYsVezsNrxUg" alt=""><figcaption></figcaption></figure>

> Both the "Activating your domain" (in-progress) and "Custom domain activated" (success) states, side by side if possible. This reassures users that a wait screen is expected and not an error.

## View custom domain information

Once setup is finished, the **Custom domain** section on the Organization settings page shows one of two states:

* **Still validating:** *"Custom domain is currently being validated: Waiting for CNAME validation with your DNS provider or registrar."* Shown with **Continue configuration** (reopens the wizard where you left off) and **Remove domain and back to default** buttons.
* **Enabled:** a green **"Custom Domain Enabled"** confirmation with your live URL shown as a clickable link, plus **Manage domain** and **Remove domain and back to default** buttons.

<figure><img src="/files/LCWT2eGmfVItHoqlmEPS" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/vntqL0W2QYsVezsNrxUg" alt=""><figcaption></figcaption></figure>

> Both states, "currently being validated" and "Custom Domain Enabled," so readers can tell which one they're looking at.

{% hint style="warning" %}
**The first time you visit your new custom domain**, you may need to log in again. This refreshes your session for the new address. If you're seeing errors or getting logged out unexpectedly right after setup, this is expected, just log in again on the custom domain.
{% endhint %}

{% hint style="info" %}
**If the link doesn't load right away:** clicking your custom domain link immediately after verification can be too early; the domain may not be fully ready to receive traffic yet. Try reloading the page, or wait a few minutes and try again.
{% endhint %}

Click **Manage domain** to review your saved domain details at any time.

## Remove a custom domain

On the **Custom domain** section, click **Remove domain and back to default**.

Diaflow asks you to confirm before removing it. Once removed, your workspace switches back to its default Diaflow address, and users can no longer sign in using the custom domain.

### Need help?

* Need to update your workspace branding or web address? Go to [Workspace settings](broken://spaces/Rdo1pkMnofwxf3lpWftw/pages/57CGNwAcpxFLizSiDoZl).
* Need to manage access for teammates who use this workspace? Go to [Users](/workspace/users.md).
* Need help with domain setup or DNS records? Contact <support@diaflow.io>.