Guide

How to add custom domains to your SaaS

Letting a customer serve your product on their own domain comes down to three things that must happen in order: a DNS record has to route their hostname to your platform, you have to verify that the person really controls that hostname, and a TLS certificate has to be issued so the site loads over HTTPS. You can build this pipeline yourself, or you can use managed infrastructure that runs all three steps for you. This guide walks through each step and the honest tradeoff between the two approaches.

This pattern is often called bring your own domain, and it is the core of any custom domains for SaaS feature. The mechanics below are true of DNS and TLS in general. For the exact records and API calls Custom Domain gives you, see the documentation rather than any hardcoded value here.

Step 1. Decide subdomain versus apex

The first decision shapes everything after it. A subdomain like app.acme.com is the common case and the easier one, because a subdomain can hold a CNAME record that points at a target hostname you control. An apex domain like acme.com sits at the root of the zone and, under the original DNS rules, cannot hold a CNAME at all. That constraint is why apex support usually needs A or AAAA records, or a provider-specific flattening feature, instead.

Encourage customers toward a subdomain when you can. If you need to support the apex, plan for the record types your platform accepts there. The full contrast is covered in apex domain versus CNAME, which explains why the same trick that works on a subdomain fails at the root.

Step 2. Point DNS at your platform

Once the shape is decided, the customer adds a record in their DNS provider that routes traffic to you. For a subdomain, that is almost always a CNAME. Conceptually it reads like this:

app.acme.com. CNAME target-your-platform-gives-you

The right side is a target hostname your platform assigns. Do not guess it or copy it from a tutorial, because it is specific to your account and your setup. For an apex domain, the equivalent is an A record, and often an AAAA record for IPv6, pointing at the addresses your platform publishes:

acme.com. A 203.0.113.10

The address above is a documentation placeholder, not a real target. The general rule holds regardless: a CNAME delegates a subdomain to a hostname you own, and A or AAAA records point an apex at fixed addresses. DNS changes also take time to spread because resolvers cache old answers for the length of the record TTL, so a freshly added record may not resolve everywhere for minutes or, in stubborn cases, longer.

Step 3. Verify ownership

Routing a hostname to you is not proof that the customer is allowed to. Without a verification step, anyone could point a domain they do not control at your platform and try to claim it. The standard defense is a proof record: you generate a unique token, the customer publishes it as a TXT record on the domain, and you confirm the token you read back matches the one you issued.

A verification TXT record looks roughly like this:

_your-verify.acme.com. TXT "verify=a1b2c3d4e5f6"

Because only someone with edit access to the zone can add that record, a matching token is strong evidence of control. Keep tokens unique per domain and per attempt, expire them after use, and re-check periodically so a domain that later moves away from you does not keep a stale claim. In many setups the same TXT mechanism also feeds the certificate step that follows, since certificate authorities accept DNS proof too.

Step 4. Issue and renew TLS

A verified, correctly routed domain still shows a browser warning until it has a valid certificate. Certificates are issued over ACME, the automated protocol behind Let's Encrypt and other authorities. The authority asks you to prove control of the hostname, usually by serving a token over HTTP or by publishing a DNS record, and then signs a certificate for it. Certificates are short lived, so renewal is not optional; it has to run automatically on a schedule well before expiry.

Two ideas matter at scale. The first is issuing a certificate the moment a new hostname is first requested rather than pre-provisioning every possible domain, which keeps you from managing certificates for names nobody uses. That approach is on-demand TLS. The second is handling thousands of customer domains, each with its own certificate, behind shared infrastructure, which is the discipline of multi-tenant TLS. Getting renewal, rate limits, and failure retries right across many tenants is where most homegrown pipelines start to hurt.

Step 5. Build versus buy

You now have the full picture, so here is the honest tradeoff. Building it yourself is entirely doable. The individual pieces are standard: create DNS records, check a TXT token, run an ACME client. The cost is not the first working demo, it is everything after. You take on certificate renewal that must never lapse, rate limits at the certificate authority, edge routing that maps an arbitrary incoming hostname to the right tenant, retries when a customer edits DNS at the wrong moment, and a support burden when a customer stares at a DNS panel they have never opened before. That work is ongoing, and it competes with your actual product.

Managed infrastructure buys back that time. Custom Domain runs all four earlier steps end to end. It detects the customer's DNS provider and, where possible, writes the records for them, so the end user often never opens a DNS panel at all. It handles ownership verification, issues certificates over ACME, and renews them on schedule behind shared edge infrastructure built for many tenants at once. It also exposes the same flow to AI agents over MCP, so an agent can add a domain programmatically. You integrate once and hand off the operational weight. For the exact records, endpoints, and SDK calls, see the documentation, since those are specific to your account and change over time.

Build if custom domains are a core competency you want to own outright and you have engineers to keep the pipeline healthy. Buy if you would rather ship the feature this week and spend your time on the product your customers actually pay for.

Frequently asked questions

Can a customer use a root domain like acme.com, not just a subdomain?

Yes, but the mechanics differ. A subdomain uses a CNAME, while an apex domain needs A or AAAA records or a provider flattening feature, because the original DNS rules do not allow a CNAME at the root. See apex domain versus CNAME for the full contrast.

How long until a newly added domain works?

Usually minutes. DNS changes propagate as caches expire based on the record TTL, and the certificate is issued once the hostname resolves and ownership is confirmed. Very stale caches or a slow registrar can stretch that out, so build in a pending state rather than assuming it is instant.

Do I have to renew certificates myself?

If you build the pipeline yourself, yes, and it must run automatically well before expiry because certificates are short lived. With managed infrastructure the renewal runs for you on schedule. See on-demand TLS for how issuance is triggered.

What stops someone from claiming a domain they do not own?

The ownership verification step. You issue a unique token, the customer publishes it as a TXT record, and you only activate the domain once you read the matching token back. Only someone with access to the zone can add that record.

Can an AI agent add a domain instead of a person?

Yes. Custom Domain exposes the same flow over MCP, so an agent can request a domain, drive verification, and check status programmatically. The available operations are described in the documentation.