# Custom Domain

Serve the sign-in experience from your own domain instead of the default platform host.

Requires: customDomain

> **Plan note:** Custom domains are available on the Essential plan and above. See [Plans & add-ons](https://dts-identity.com/docs/getting-started/plans-and-addons.md). On lower tiers, sign-in is served from the default platform host.

> **Note:** A custom domain is not configured in the Admin Console. Setup runs in the separate portal that manages your instance. This page explains what a custom domain changes and what to prepare before setup.

By default your tenant is reached at a platform-managed host. With a **custom domain** your users sign in at a hostname you own, for example `auth.yourcompany.com`, so the sign-in pages, the links in platform emails and the OIDC endpoints all use your own domain. This keeps the experience consistent with the rest of your service.

## What to prepare

| Item | Details |
|---|---|
| **A dedicated hostname** | A subdomain used only for sign-in, such as `auth.yourcompany.com`. Do not reuse the hostname of an existing website. |
| **Access to the DNS zone** | Two records are published for the hostname: a **CNAME** that routes traffic to the platform, and a **TXT** record that proves you own the domain. The exact host names and values are shown during setup. |
| **A TLS certificate (optional)** | Only if you want to use your own certificate instead of a managed one. Have the full PEM certificate chain and the matching private key ready. The certificate must cover the hostname and must not be expired. |

## How setup runs

The steps happen in a fixed order:

1. **Domain registered.** The hostname is recorded for your instance.
2. **Ownership verified.** You publish the TXT and CNAME records at your DNS provider. Verification succeeds once the records have propagated, which usually takes a few minutes.
3. **Certificate chosen.** Either a managed certificate is issued and renewed automatically, or your own certificate and private key are supplied.
4. **Domain activated.** The domain is wired up at the edge and sign-in switches over to it. Activation takes a moment and can briefly interrupt active sessions.

## After activation

- The sign-in pages, multi-factor prompts, consent screen and end-user portal are served from your domain.
- The OIDC issuer and all endpoints use the new hostname. Applications that read the [discovery document](https://dts-identity.com/docs/quickstarts.md) pick this up automatically; anything with hard-coded endpoint URLs has to be updated.
- Links in platform emails point at the new hostname.
- Leave the DNS records in place for as long as the domain is in use. Removing them breaks sign-in.

## Troubleshooting

- **Ownership verification does not complete.** DNS changes can take a few minutes, sometimes longer, to propagate. Check that the record host and value match exactly what the setup shows, with no extra characters.
- **CNAME conflict.** Make sure no A or AAAA record exists for the same hostname.
- **Certificate rejected.** In *own certificate* mode the certificate must be a valid PEM chain, must match the private key, must cover the hostname (CN or SAN) and must not be expired.
- **Sign-in still uses the old host.** Activation is the last step and is separate from verification. Confirm the domain shows as active before switching your users over.

## See also

- [Appearance](https://dts-identity.com/docs/branding/appearance.md)
- [Branding overview](https://dts-identity.com/docs/branding.md)
