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

# Custom Domain

> Serve the hosted verification screens and OIDC endpoints from your own domain.

A **custom domain** puts the hosted flow on your brand's hostnames. Set it up in the Console under **Developers → Custom Domain**. Custom domains are available for **production apps**.

## Two hostnames

| Host | Serves | Example |
| :- | :- | :- |
| **Web Frontend URL** | The hosted verification screens | `verify.example.com` |
| **OIDC Backend URL** | The OIDC endpoints | `connect.example.com` |

The two hosts must be **different** and share the **same base domain**.

With an active domain, users start at `https://<oidc host>/v2/auth`.

<Warning>
  The issuer does not change: ID tokens and the discovery document on your domain still say `https://connect.hopae.com`. Keep your library's issuer at `https://connect.hopae.com` and override only the authorization endpoint with `https://<oidc host>/v2/auth`.
</Warning>

## Set up

<Steps>
  <Step title="Enter both hosts">
    The Console shows the DNS records to add.
  </Step>

  <Step title="Add every DNS record, for both hosts">
    Routing (`CNAME`), ownership (`TXT`), and certificate validation records. A missing record keeps the domain from going live.
  </Step>

  <Step title="Wait for active">
    Keep the page open or click **Refresh**. The Console re-checks DNS and the certificate. Hopae does not check in the background and sends no webhook. A missing record keeps the domain in `awaiting_dns`.
  </Step>
</Steps>

## Statuses

```mermaid theme={null}
stateDiagram-v2
    direction LR
    [*] --> unconfigured
    unconfigured --> awaiting_dns: enter hosts
    awaiting_dns --> verifying: records found
    verifying --> active: certificate issued
    verifying --> invalid: provisioning failed
```

| Status | Meaning |
| :- | :- |
| `unconfigured` | No custom domain |
| `awaiting_dns` | Add the DNS records |
| `verifying` | Ownership confirmed, certificate being issued. Not live yet |
| `active` | Live |
| `invalid` | Provisioning failed repeatedly. Contact [support@hopae.com](mailto:support@hopae.com) |

Rely on the domain only once it is `active`. Until then, authorization requests to your OIDC host are redirected to Hopae's own host.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.