Multi-tenant custom domains
The architecture pattern for a SaaS serving thousands of customer-owned hostnames from a shared application backend, including per-domain TLS and per-domain routing.
Multi-tenant custom domains is the technical pattern where one application backend serves traffic from many different hostnames, each owned by a different customer, while keeping their data isolated.
The four pieces
- Per-domain TLS certificates. Every customer hostname needs its own valid cert. At scale, this means automated issuance via Let's Encrypt's ACME protocol. A real production setup has issuance, renewal, and revocation paths.
- A request router. Your edge inspects the incoming Host header (or SNI), looks up which tenant owns that hostname, and routes the request to their data.
- Per-tenant context propagation. Every request that goes from your edge to your app servers carries some marker (a header, a path prefix, a token) that tells the app which tenant's content to serve.
- DNS monitoring. Customers change their DNS. You need to know when their CNAME breaks so you can surface "your domain is offline" in your dashboard before they email support.
The hard parts
Certificate provisioning at scale. Let's Encrypt rate-limits to 300 new certs per registered domain per 3 hours and 50 per account per 3 hours. Once you have more than a few thousand customer hostnames, you're hitting rate limits and need either a paid CA or careful batching.
Routing latency. Looking up "which tenant owns janesbakery.com" on every request must be sub-millisecond. Most teams cache the lookup in memory at the edge with periodic refresh.
Cold-start cert issuance. First request to a brand-new domain has to wait while ACME negotiates the certificate (5–30 seconds). If that first request is a slow browser timeout, you lose the user. Common mitigation: issue the cert pre-emptively as soon as DNS verification passes, not on first request.
Why most teams adopt a service
Building this is 4–8 weeks of focused engineering for v1 and then it requires ongoing care as Let's Encrypt rate limits, ACME protocol versions, and certificate transparency rules evolve. A custom-domain API abstracts all of it.