> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conduit.financial/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domains

> Serve the verification and signing pages your customers' signers use on a web address you own, with your branding and your name in the address bar.

By default, the people who approve payments on your customers' wallets are sent to a Conduit web address. With a custom domain, they are sent to an address you own — for example `https://verify.yourcompany.com` — carrying your logo, your colors, and your name in the address bar.

Only the signer-facing pages move. Your own team keeps using the Conduit dashboard at its normal address, so your admin and login surface stays separate from the pages you hand to third parties.

<Note>
  Setup happens in the Conduit dashboard, not through the API. There are no endpoints on this page. Budget a few minutes plus however long your DNS provider takes to publish changes.
</Note>

## Prerequisites

* **A subdomain you control**, such as `verify.yourcompany.com` or `pay.yourcompany.com`. Root domains like `yourcompany.com` are not supported.
* **Access to your DNS**, either directly or through whoever manages it.
* **An admin on your organization**, because enabling the domain requires an admin approval.

One active custom domain per organization, and a domain can only be claimed by one organization.

## Set up the domain

<Steps>
  <Step title="Enter the address">
    Go to **Settings → Custom domains**, type the subdomain you plan to use, and click **Add**.
  </Step>

  <Step title="Copy the two DNS records">
    The page shows exactly what to create, each row with a copy button. One record proves the domain is yours; the other points it at Conduit.

    | Type  | Name                                     | Value                              |
    | ----- | ---------------------------------------- | ---------------------------------- |
    | TXT   | `_conduit-verify.verify.yourcompany.com` | `conduit-domain-verify=YOUR_TOKEN` |
    | CNAME | `verify.yourcompany.com`                 | `domains.conduit.financial`        |

    <Warning>
      Work from the dashboard, not from this table. The page shows your real subdomain and your real token.
    </Warning>
  </Step>

  <Step title="Add the records at your DNS provider">
    Paste both rows into Cloudflare, Route 53, GoDaddy, or wherever your DNS lives.
  </Step>

  <Step title="Verify">
    Click **Verify**. Conduit checks both records live and reports, per record, whether it matched and what is wrong when it did not.
  </Step>

  <Step title="Wait for Active">
    Once verification passes, Conduit obtains the HTTPS certificate automatically. The page shows an **Issuing** state and flips to **Active** when the domain is live, usually within a few minutes. No refresh needed.
  </Step>
</Steps>

### If your DNS publishes CAA records

Most domains do not. A CAA record is a list of certificate authorities allowed to issue for your domain, and Conduit's certificates come from Let's Encrypt. If you have CAA records and Let's Encrypt is not among them, add:

| Type | Name              | Value                       |
| ---- | ----------------- | --------------------------- |
| CAA  | `yourcompany.com` | `0 issue "letsencrypt.org"` |

It goes on your root domain, not on the subdomain. A name holding a CNAME may hold no other record, so your DNS provider will reject a CAA record at `verify.yourcompany.com`. Conduit climbs from the subdomain until it finds a CAA set, and your root is the first one it reaches.

Verify tells you explicitly when this is the blocker.

## Statuses

| Status          | What it means                                                                                                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Pending DNS** | Your records have not been found yet. Add them and click Verify.                                                                                                      |
| **Verified**    | Records look good. Certificate work is starting.                                                                                                                      |
| **Issuing**     | Getting the certificate. This is the normal wait before the domain goes live.                                                                                         |
| **Active**      | Live and serving. A signer's own activation link moves to your domain as soon as that signer re-enrols; payout-approval links move once every signer has re-enrolled. |
| **Failed**      | Something broke, most often a DNS record that disappeared. The page explains what to fix.                                                                             |
| **Disabled**    | The domain was switched off and is no longer serving.                                                                                                                 |

When a check fails, the page tells you what to fix in plain language rather than showing a raw error.

## Certificates are handled for you

You never generate a key, produce a certificate signing request, or upload a certificate. Conduit requests the certificate and renews it for the life of the domain. Nothing expires on your calendar, and there is no renewal fee.

## Keep the DNS records in place

Conduit rechecks your records daily. If they disappear, the domain moves to **Failed** and keeps serving for 72 hours after the last successful check, then switches off. Restoring the records and clicking **Verify** brings the domain back at any point, before or after it switches off.

<Warning>
  This automatic switch-off does not run the safety check that removal runs. A signer whose only passkey lives on your domain is locked out by it, which is the one thing removing the domain yourself will not let you do. Keep the records in place, and if the domain does switch off, restore them and re-verify before asking those signers to approve anything.
</Warning>

## Plan for passkeys

Your customers' signers approve payments with passkeys, and a passkey is permanently tied to the single web address where it was created. That is a browser security rule, not a Conduit choice, so a passkey created on a Conduit address cannot be used on yours.

<Note>
  Turning the domain on first does not avoid this. A signer's first passkey is always created on the Conduit address, because the link that enrols them can only move to your domain once they already hold a passkey there.
</Note>

Each signer re-enrols once:

1. When your domain goes live, Conduit emails a link to every signer who does not yet have a passkey on it. This email is sent once, on that transition.
2. The link opens a page on the Conduit address where the signer **signs in with their existing passkey**. The email is not a credential — on its own it grants nothing.
3. Once signed in, the signer is moved to your domain and creates a new passkey there.

Each re-enrolment may need one admin approval. There are no documents and no re-verification.

<Warning>
  Signers you add after the domain is live are not emailed, because that email is sent only when the domain goes live. They enrol on the Conduit address like everyone else, and an administrator has to send them the migration link to move them across: `/signer-profile/migrate?domain=` followed by your domain, on the Conduit address. Until they move, your organization's payout-approval links stay on the Conduit address for everyone, because those links go to every possible approver.
</Warning>

<Note>
  There is no deadline. Until a signer re-enrols they keep receiving links on the Conduit address, and their original passkey is kept as a working fallback — so a half-finished migration is harmless and nobody loses access.
</Note>

Enabling the domain requires an admin at your organization to approve the change, so your signers' sign-in address cannot be moved without you.

## Turn it off

Removal is self-serve from the same settings page; admins do not need to contact support. Verification links immediately go back to the Conduit address, and your signers' original passkeys keep working.

The one case that needs work first is signers who have only ever had a passkey on your domain, meaning they joined after it went live. Conduit blocks removal and names them, so you can move them back before anything is switched off rather than discovering a lockout afterwards.

To clear each named signer, give them a passkey on the Conduit address: send them to `/signer-profile/migrate` on your own domain, which runs the move in reverse, or run credential recovery for them. Once every named signer holds one, removal goes through.

## What happens next

* A signer's own activation link moves to your domain as soon as that signer re-enrols. Payout-approval links go to everyone who might approve, so they stay on the Conduit address until every signer has re-enrolled. The flow is unchanged either way — see [Non-custodial payout lifecycle](/guides/non-custodial-payout-lifecycle).
* Your webhook payloads carry the verification URL, which may be on your domain or on the Conduit address while signers are still re-enrolling. Treat the URL as opaque and always use the most recent one you received.
* Branding on the signer pages comes from the logo and colors you configure under **Branding**.