Skip to main content
By default, your users see Hopae-hosted URLs during verification. A custom domain lets you serve the hosted verification UI and the OIDC backend from your own branded hostnames instead, so the whole flow stays on your brand.

​
The two hosts

A custom domain configures two hostnames, and they play different roles:
The two hosts must be different from each other and must share the same base domain. For example, verify.example.com (web) and connect.example.com (oidc) are both under example.com — valid. Using the same host for both, or hosts on different base domains, is rejected.

​
Status and lifecycle

A custom domain moves through a small set of states. You can read the current state at any time and show it in your own UI.

​
Verified vs. active

Two milestones are easy to confuse:
  • Verified — your DNS records are in place and Hopae has confirmed you control the domain. This is the verifying checkpoint passing.
  • Active — the SSL certificate has been issued and the domain is live and serving traffic. This is the active status.
A domain can be verified but not yet active: ownership is confirmed (verifying) while the SSL certificate is still being issued. Only rely on the domain once it reaches active.

​
DNS records

When you configure a custom domain, Hopae gives you a set of DNS records to add at your DNS provider. Add every record shown, for both hosts (web and OIDC) — the domain only goes active once they are all in place. The records fall into three kinds:
Partial records are not enough. If any record is missing, verification stays at awaiting_dns or verifying and the domain never reaches active. Add every record shown for both the web and OIDC hosts.

​
How status advances

Status only changes when you trigger a verify. There is no background polling and no webhooks for custom domain status — Hopae does not re-check your DNS on its own.
  • After you add the DNS records, call the verify action (POST .../custom-domain/verify).
  • Each verify re-checks DNS and SSL and returns the updated state.
  • Repeat verify (poll) until the status reaches active.
  • Reading the domain with GET .../custom-domain is read-only — it returns the stored state but never advances it.
In the Console, the custom domain screen calls verify for you on a short interval and when you click Refresh. If you integrate directly against the Workspace API, you own the polling — call verify until the status is active.

​
See also