Why it matters
A custom hostname looks like a DNS setting, but it spans ownership checks, routing, certificate issuance and renewal. Customers need a clear setup path and a safe fallback when DNS changes.
The product must decide which tenant owns a hostname before routing requests. Certificates may take time to issue, and an old tenant must not keep serving a domain after ownership changes.
Decisions to make
- Choose whether customers use a CNAME, A record or delegated zone.
- Define how hostname ownership is verified and transferred.
- Plan wildcard, apex-domain and subdomain support.
- Set behavior while DNS or certificates are pending.
- Decide what happens to links and cookies across branded hosts.
Build checklist
- Validate hostname format and prevent duplicate tenant claims.
- Show DNS records, verification state and propagation diagnostics.
- Automate certificate issuance and renewal monitoring.
- Route only verified hosts to their owning tenant.
- Test removal, transfer, failed renewal and certificate expiry.
Common mistakes
- Routing a hostname before proving tenant ownership.
- Assuming certificate issuance is instantaneous.
- Using a cookie domain that leaks sessions between customer hosts.
Tools & references
3 starting points to compare or study. Check fit, maintenance, terms and current capabilities before choosing one.
