Wildcard subdomains for multi-tenant apps: DNS, SSL, and routing

A wildcard subdomain is a DNS record named *.example.com. It answers for any name under example.com that has no record of its own, so acme.example.com, globex.example.com, and every tenant you sign up next all reach the same app without a new DNS record each time. Multi-tenant SaaS apps use it to give every customer their own subdomain on day one.

A working setup needs three parts, and most guides only cover the first:

1. A wildcard DNS record that sends every tenant name to your host.
2. A wildcard TLS certificate for *.example.com. Let's Encrypt, which most hosting platforms use, issues these only through DNS validation, so your host needs a way to write _acme-challenge records in your zone.
3. Routing in the app that reads the hostname, finds the tenant, and refuses names that don't belong to anyone.

This post covers all three, with the records each hosting platform asks for as of 2026-11-03, and how to provision the wildcard with Domain SDK.

How a wildcard DNS record matchesCopy Anchor Link

RFC 4592 defines the rules, and three of them catch people out:

• The wildcard only answers for names that don't exist. If api.example.com has any record at all, even just a TXT record, the wildcard no longer answers for it. Queries for its A record get "no data", not the wildcard's answer. Give each subdomain you use for something else its own complete records.
• It doesn't cover the apex. *.example.com says nothing about example.com itself, which needs its own A or ALIAS record (see Apex domains).
• In DNS, it can match more than one level. *.example.com also answers for a.b.example.com when b.example.com doesn't exist. TLS doesn't follow suit, as the next section explains.

Why the certificate is the hard partCopy Anchor Link

A wildcard certificate for *.example.com covers exactly one label. RFC 9525 says a wildcard "can only match one label", so the certificate is valid for acme.example.com but not for example.com or eu.acme.example.com. Keep tenant hostnames to one label under the base domain, or plan a separate certificate for each deeper level.

Let's Encrypt, which most platforms use, issues wildcard certificates only through the DNS-01 challenge. The HTTP-01 challenge "cannot be used to issue wildcard certificates" (challenge types). DNS-01 means the platform publishes a TXT record at _acme-challenge.example.com and keeps doing so for every renewal. There are three ways to let it:

• Move the zone's nameservers to the platform, so it controls the whole zone.
• Delegate just _acme-challenge to the platform, with an NS or CNAME record at that name.
• Issue the certificate yourself, for example with certbot's DNS plugins, and upload it.

Each platform picks one of these, which is why their instructions look so different.

What each platform asks forCopy Anchor Link

Checked against each platform's docs on 2026-11-03. The last column says whether Domain SDK's adapter for that platform can provision *.example.com today.

Sources: Vercel wildcard domains, Render wildcard domains, Railway wildcard domains, Netlify HTTPS, bunny.net wildcard certificates, Cloudflare Universal SSL, Cloudflare for SaaS plans, and Workers for Platforms subdomain routing.

Railway's API does accept wildcard domains, but Domain SDK's Railway adapter keeps them disabled in v0.1, so it attaches each tenant hostname on its own. The same fallback works on Netlify and Cloudflare: one add() per tenant, each with its own certificate.

Provision the wildcard with Domain SDKCopy Anchor Link

createSubdomainClient wraps a domain client for one parent domain you own. It checks that every label is a single DNS label under that domain, rejects labels you reserve, and gives you provisionWildcard() when the platform supports it. Create the clients in a module with no side effects, so any part of the app can import them:

import {
  createDnsClient,
  createDomainClient,
  createSubdomainClient,
} from "@opencoredev/domain-sdk";
import { porkbun } from "@opencoredev/domain-sdk/porkbun";
import { vercel } from "@opencoredev/domain-sdk/vercel";

const domains = createDomainClient({
  provider: vercel({
    token: process.env.VERCEL_TOKEN!,
    projectId: process.env.VERCEL_PROJECT_ID!,
  }),
});

export const subdomains = createSubdomainClient({
  domainClient: domains,
  baseDomain: "example.com",
  // These never become tenants, so a signup can't claim them.
  reservedLabels: ["www", "api", "app", "admin", "mail", "status"],
});

export const dns = createDnsClient({
  provider: porkbun({
    apiKey: process.env.PORKBUN_API_KEY!,
    secretApiKey: process.env.PORKBUN_SECRET_API_KEY!,
  }),
});

Then provision the wildcard once, from a setup script rather than from request code. The sample runs on Vercel and writes the routing record into a Porkbun zone:

import { dns, subdomains } from "../lib/subdomains";

if (!subdomains.supportsWildcard) {
  throw new Error("This platform has no wildcard support: attach each tenant at signup.");
}

// Attaches *.example.com to the Vercel project.
const wildcard = await subdomains.provisionWildcard();

// Writes the required routing and ownership records Vercel returned.
await dns.applyDomainRecords(wildcard, { zone: "example.com" });

// Vercel's certificate also needs DNS-01 access: Vercel nameservers, or the two
// _acme-challenge NS records from the table above. The Porkbun, Namecheap, and
// Spaceship adapters don't write NS records, so add those in the DNS host's dashboard.
await subdomains.waitUntilWildcardActive();

With the wildcard active, signing up a tenant is a database write, not a platform call. On platforms without wildcard support (Netlify, Railway, and Cloudflare for SaaS in Domain SDK), each signup attaches its own hostname instead:

import { dns, subdomains } from "./subdomains";

export async function claimSubdomain(input: string) {
  // Throws INVALID_HOSTNAME for "admin", "a.b", or "*".
  const hostname = subdomains.toHostname(input); // "Acme" -> "acme.example.com"
  const label = subdomains.fromHostname(hostname); // "acme"

  // Save { label, hostname } here, with a unique constraint on label.

  if (!subdomains.supportsWildcard) {
    const domain = await subdomains.add(label);
    await dns.applyDomainRecords(domain, { zone: "example.com" });
    await subdomains.waitUntilActive(label);
  }
  return hostname;
}

waitUntilWildcardActive() returns once the platform reports the wildcard as active. That's the platform's own status, not a separate certificate check, so open one tenant URL over HTTPS before you announce it. Poll until active covers the polling options.

Route tenants in Next.jsCopy Anchor Link

Next.js 16 renamed middleware.ts to proxy.ts (proxy file convention). The proxy runs before every route, reads the Host header, and rewrites tenant requests to a route that takes the tenant as a parameter:

import { NextResponse, type NextRequest } from "next/server";

const BASE_DOMAIN = "example.com";
const RESERVED = new Set(["www", "api", "app", "admin", "mail", "status"]);

export function proxy(request: NextRequest) {
  const host = (request.headers.get("host") ?? "").toLowerCase().replace(/:\d+$/, "");
  const url = request.nextUrl.clone();
  const label = host.endsWith(`.${BASE_DOMAIN}`) ? host.slice(0, -BASE_DOMAIN.length - 1) : "";

  // The main site, reserved names, and deeper names like eu.acme.example.com,
  // which the *.example.com certificate doesn't cover anyway.
  if (!label || label.includes(".") || RESERVED.has(label)) {
    // Keep the internal tenant routes unreachable from the main site.
    if (url.pathname === "/tenants" || url.pathname.startsWith("/tenants/"))
      return new NextResponse(null, { status: 404 });
    return NextResponse.next();
  }

  url.pathname = `/tenants/${label}${url.pathname}`;
  return NextResponse.rewrite(url);
}

export const config = {
  // API routes and static assets stay shared; route handlers can read the Host header.
  matcher: ["/((?!api/|_next/|favicon.ico).*)"],
};

Then app/tenants/[tenant]/[[...path]]/page.tsx looks the label up and calls notFound() when no tenant owns it. Never fall back to a default tenant: with a wildcard record in place, any name anyone types reaches your app.

Security notesCopy Anchor Link

• Reserve labels before launch. www, api, admin, mail, status, and anything you might use later. Renaming a tenant who signed up as admin is harder than blocking it.
• Keep cookies host-only. A cookie set with Domain=example.com goes to every tenant's subdomain. Leave out the Domain attribute for session cookies so each tenant's cookie stays on its own hostname.
• Think about the Public Suffix List if tenants can publish their own HTML or scripts. Pages on acme.example.com can set cookies for example.com, which is why hosts like github.io are listed on the Public Suffix List.
• Remove the wildcard when you shut a service down. A * CNAME that still points at a platform hostname you no longer own is an open invitation for a subdomain takeover.

When not to use a wildcardCopy Anchor Link

Wildcards suit subdomains of a domain you own. When customers bring their own domains, like app.customer.com, every hostname is in a different zone, so each one needs its own record and certificate. That's the custom-domain flow covered in the Cloudflare for SaaS guide and the provider docs. Many apps offer both: a free acme.example.com from the wildcard, and a custom domain as an upgrade.

Common questionsCopy Anchor Link

What is a wildcard subdomain?Copy Anchor Link

A DNS record whose leftmost label is *, such as *.example.com. It answers for any subdomain that has no records of its own, so new subdomains work without new DNS records.

Does *.example.com cover example.com?Copy Anchor Link

No. Neither the DNS record nor the certificate covers the apex. Add an A or ALIAS record for example.com, and make sure the certificate lists it too. Render requires the root domain to point to Render before a wildcard works there.

Does a wildcard certificate cover a.b.example.com?Copy Anchor Link

No. A wildcard in a certificate matches exactly one label. The DNS wildcard may answer for a.b.example.com, but browsers will reject the certificate, so keep tenants one level deep or issue *.b.example.com separately.

Can I get a free wildcard certificate from Let's Encrypt?Copy Anchor Link

Yes, through the DNS-01 challenge only. Most platforms do it for you once they can write _acme-challenge records in your zone, through their nameservers or a delegated _acme-challenge record.

Can I still give some subdomains their own records?Copy Anchor Link

Yes. An explicit record always beats the wildcard for that name. Just remember that any record at a name, even a TXT record, stops the wildcard from answering there.

Next stepsCopy Anchor Link

• Give tenants managed subdomains: the full createSubdomainClient guide, including label claiming.
• createSubdomainClient reference: every method and what it rejects.
• Vercel custom domains, Render custom domain, and bunny.net: the adapters with wildcard support.
• Apex domains: A records, ALIAS, and CNAME flattening: the record the wildcard doesn't cover.
• Porkbun API and Namecheap API: writing the records from TypeScript.