Adding a domain field to a tenant table is not a complete custom-domain feature. Ownership verification, DNS configuration, TLS issuance and routing can succeed or fail independently. Model that lifecycle explicitly instead of declaring success when a hostname is saved.
Represent useful states
An application might use pending_verification, pending_dns, pending_certificate, active and failed states. These are design suggestions, not universal provider statuses. Record the latest check and a useful failure reason. Normalize hostnames and reject paths or complete URLs in a field intended for a hostname.
Verify the right to bind
A request to add example.com does not prove control of it. Use the provider’s ownership challenge and a unique binding so one hostname cannot belong to two tenants. Do not reuse challenge tokens between tenants. Cloudflare distinguishes hostname validation from certificate-related validation; treat them as separate requirements.
Separate DNS from TLS readiness
Show the exact records returned by the hosting provider rather than assuming one universal A or CNAME recipe. Check both destination and certificate status before activating. Use bounded polling and a clear retry action. Keep the management interface accessible on a trusted platform domain when a customer domain is unavailable.
Claim hostname -> verify ownership -> check DNS target
-> validate certificate -> activate routing
Remove hostname -> stop routing -> release provider binding
Route only known active names
Resolve a normalized hostname through an active binding. Do not derive tenant identity from arbitrary Host values or untrusted forwarding headers. Unknown names should not fall back to another customer’s data. Treat the apex domain and www as separate names requiring an intentional binding or redirect decision.
Review sessions and canonical URLs
Domains affect cookies, OAuth callbacks and emailed links. Avoid unnecessarily broad cookie scope and decide where login belongs. For public content available on both a platform address and a custom domain, use consistent canonical URLs and appropriate redirects. Do not apply a blanket redirect to APIs or webhook endpoints without reviewing their contracts.
Make removal a supported operation
Disable routing, release provider bindings and explain any remaining customer DNS records. Rebinding should follow the application’s verification policy. Test certificate expiry, DNS changes and provider failures. Reliable onboarding includes an understandable exit path and recovery behavior, not only a successful first page load.
Scenario: correct DNS but pending TLS
When DNS points to the intended destination but the certificate is pending, explain that routing and TLS readiness are distinct stages. Show the latest check and the provider’s actual requirements. Do not ask a customer to change an already correct record without evidence. Keep the binding inactive until required conditions hold while preserving access through the platform’s temporary address.
Test a domain transfer between tenants
Test removing a binding from one account and claiming it from another. A leftover DNS record should not expose the previous account or bypass the new verification policy. Review routing-cache invalidation on removal. Send requests during the transition and confirm that an unknown hostname cannot fall back to a default tenant or a page containing the previous tenant’s data.
Official references
These references document the tools discussed. Examples and design decisions are illustrative and should be adapted to the project and its versions.
Prepared by: Noor Yasser
Working through a similar engineering challenge?
I help teams turn architecture decisions into a clear scope and dependable, reviewable implementation.
