A strong fit
- Many independently owned customer domains
- One tenant-aware HTTPS application
- Customer-domain provisioning triggered by product workflows
- Operations need a queryable inventory and explicit statuses
For multi-tenant platforms
Every tenant hostname. One application boundary.
Treat every customer domain as an explicit resource with separate DNS, certificate and routing statuses. The edge accepts only registered hostnames; your application resolves the tenant from X-Forwarded-Host.
- Application model
- Multi-tenant
- Domain inventory
- Explicit resources
- HTTPS destination
- Your public service
alpha.comportal.beta.ioworkspace.gamma.eu
Registered hosts onlyEdge routingHTTPS destinationapp.yoursaas.comX-Forwarded-Host preserved
Choose your path
This guide is for an inventory, not only a setting.
Choose the path that matches the operating responsibility already inside your product.
Architecture fit
Use a customer-domain resource when the hostname belongs to a tenant.
This model works when your application already knows how to select the tenant from a registered hostname and you need the infrastructure around that hostname to be reliable.
Keep in your application
- Tenant authorization and access control
- Hostname-to-tenant mapping
- Redirect and canonical URL policy
- Business rules for adding and removing domains
Request path
The edge validates the hostname. Your app resolves the tenant.
Registration is an allowlist boundary, not a replacement for application-level isolation.
Operating model
Inventory and status polling replace proxy configuration.
A platform integration should be designed around resources and explicit status transitions, not individual infrastructure commands.
Platform eventYour servicesubdomain.to
Tenant requests a hostnameAuthorize and create the customer domainReturn DNS instructions and emit hostname.created
Customer domain is activatingPoll GET /domains/{id}pending_dns → validating → provisioning
Customer domain becomes activeExpose the branded URLReport separate DNS, certificate and routing statuses
Tenant removes the hostnameApply product policy and deleteEmit hostname.deleting and remove the route
Failure design
Treat each subsystem as a separate support status.
The lifecycle status should tell operators who can act next. Exception statuses are misconfigured, failed, suspended and deleting.
The customer can act.
Show the expected CNAME for a subdomain or A record for an apex domain.
An operator should investigate.
Keep the customer domain out of production and surface the affected subsystem status.
The infrastructure is progressing.
Continue polling the resource; do not ask the customer to change a valid DNS record again.
The request is rejected.
An unknown hostname or SNI mismatch does not traverse the custom-domain edge.
Responsibility boundary
Scale the tenant model, not the certificate system.
Your platform remains the system of record for customers. subdomain.to becomes the system of record for each customer domain’s infrastructure status.
Platform teamsubdomain.to
Tenant and hostname ownership policyDNS verification status
Inventory reconciliation and deletion policyCertificate issuance and renewal
Origin availability and tenant isolationStrict registered-host routing
Operator UI and customer communicationDomain status API plus created/deleting webhooks
Architecture questions
Before you import the inventory.
Can every hostname route to the same application?
Yes. The HTTPS destination must point to a public origin on port 443 or 8443. The edge rewrites Host to origin_host; resolve the tenant from X-Forwarded-Host.
Does explicit registration replace tenant authorization?
No. It restricts which hostnames can traverse the custom-domain edge. Your application still authenticates users and isolates tenant data.
How should we reconcile an existing inventory?
Keep your platform database as the business source of truth, store domain identifiers and poll the API for status. Webhooks currently cover only hostname.created and hostname.deleting.
Does all traffic stay in Europe?
The control plane runs in eu-west-3. This does not mean every HTTPS request path remains within Europe.