Custom Domains
The platform's default URL grammar leads with <orgSlug>.api.k9o.io — a clean, memorable shape that carries the customer's slug. For some customers — regulated-industry brands, multi-tenant SaaS hosts, enterprises with strict brand-sovereignty requirements — the Kilimanjaro subdomain itself is the wrong default. They want end-users hitting auth.acme-corp.com, not acme.api.k9o.io. The platform's custom-domain capability lets them do exactly that.
This page covers the customer-facing shape (what end-users see), the CNAME flow that maps the customer domain to the platform, the certificate provisioning model, and how multiple domains are registered per project.
1. What custom domains do
A customer configures one or more CNAMEs pointing from their domain to the platform tenant subdomain. The platform's gateway recognises the customer domain, serves the same surfaces it would have served on the platform subdomain, and Kilimanjaro becomes invisible:
| Surface | End-user URL with custom domain |
|---|---|
| Gate sign-in | https://auth.acme-corp.com/@partners/gate/signin |
| Customer data plane | https://api.acme-corp.com/@partners/data/orders/58391 |
| Function invoke | https://api.acme-corp.com/@partners/functions/process/invoke |
The cookie domain, the OAuth callback URLs, the JWT iss field, and DKIM-signed platform email all carry the customer's domain. From the end-user's perspective, the customer's brand owns the entire authentication and data-plane surface. The platform is structurally present but visually absent.
2. The CNAME flow
Custom-domain setup is a customer-driven operation in the customer's DNS, plus a one-time configuration step in the Kilimanjaro Console.
- Customer creates a CNAME in their DNS, pointing the chosen subdomain at the platform tenant subdomain. For an
acme/partnersproject, the CNAME source isauth.acme-corp.com(or whatever the customer chooses); the target isacme.api.k9o.io. - Customer registers the custom domain in the Console — Settings → Custom Domains → Add Domain. They enter the source domain (
auth.acme-corp.com). - Platform validates the CNAME — a DNS lookup confirms the source resolves to the expected target.
- Platform provisions a TLS certificate via the ACME protocol (Let's Encrypt or equivalent) for the customer's domain. The provisioning is automatic on validation; the certificate is renewed automatically on schedule.
- Platform updates its per-tenant routing table — incoming requests on the custom domain are recognised, routed to the same tenant gateway that serves the platform subdomain, with the appropriate cookie-domain and JWT-issuer rewrites.
Once configured, the custom domain serves requests immediately. The platform subdomain (acme.api.k9o.io) continues to work — customers can use both in parallel or migrate fully to the custom domain.
3. Per-tenant routing table
The platform's gateway maintains a routing table that recognises every active custom domain and resolves it to the owning org. Routing is identical to the default subdomain mode:
- Host header matches against the routing table to identify the org
- Path carries the
@<projectSlug>marker and the sub-resource as usual - Cookies are issued for the matched domain (not the platform subdomain)
- OAuth callbacks are constructed against the custom domain
- JWT
issfield is rewritten to the custom domain - Email sent on the customer's behalf (verification, MFA codes, audit notifications) ships DKIM-signed for the custom domain
The routing table is a customer-administered resource — the customer adds and removes domains, and the platform validates each one at registration.
4. Domains per project
Custom domains are a capability of every project. A project can register one or more custom domains, each validated at registration; projects that keep the platform subdomain (<slug>.api.k9o.io) continue to work in parallel. The customer-brought-cert option (see §5) is available wherever the deployment model supports it, and air-gapped deployments configure custom domains through their local configuration.
5. Customer-brought-cert option
The default certificate provisioning is automatic — the platform requests a certificate from Let's Encrypt against the customer's CNAME, validates control of the domain, and stores the resulting private key in the platform's certificate store. For customers on sovereign-cloud or air-gapped deployments with stricter cryptographic-sovereignty requirements, the platform supports a customer-brought-cert path — the customer generates the private key in their own HSM, signs the CSR through their own CA, and provides the certificate to the platform without the private key ever leaving the customer's environment.
This mirrors the HYOK pattern in Kibo — the platform holds operational access to the certificate (it can present the cert for TLS termination) but the key material remains structurally bound to the customer's hardware.
6. Customer-domain operational substance
Operating a custom domain is mostly invisible after setup. The customer's DNS team maintains the CNAME (renewal is rarely needed since CNAMEs do not expire), and the platform handles certificate renewal automatically. The customer's operational dimensions:
- DNS administration — the customer is responsible for the CNAME and any other DNS records pointing into the platform
- Certificate renewal monitoring — the platform sends notifications ahead of certificate renewal failures; the customer's incident-response workflow handles outright DNS or CA outages
- Brand-sovereignty audit — the customer can confirm at any time, from any end-user device, that the cookie domain, JWT
iss, OAuth callback, and email DKIM signatures all carry the customer's domain (Kilimanjaro is invisible) - Multi-domain routing — a customer with multiple domains chooses which domain to use for which org; the platform routing table accepts the per-domain configuration
7. Migration patterns
A customer moving from the platform subdomain to a custom domain has two paths:
- Cutover — configure the custom domain, validate, then update integrations to use the new domain. Both URLs work in parallel until the customer removes the platform subdomain integration.
- Gradual — keep the platform subdomain active indefinitely, route new integrations to the custom domain, leave old integrations on the platform subdomain. Both surface the same org; the choice is operational.
The customer does not need to coordinate with the platform on cutover timing. Once the custom domain is provisioned, both URLs serve the same org.
8. See also
- Routing Modes — the URL grammar the custom domain inherits.
- Slug Addressing — how
@<projectSlug>continues to mark the project on the custom domain. - Session Model — root and tenant sessions, with the tenant cookie domain rewritten to the custom domain.
- Kibo → HYOK — the cryptographic-sovereignty pattern the customer-brought-cert option mirrors.