Skip to content

Wildcard certificates

Give every customer their own subdomain without an API call per customer. HostStack issues one certificate for *.your-zone, renews it on its own, and routes every subdomain that has no domain of its own to one service — with the original Host header, so your app can tell the tenants apart.

When to use one

A platform that hands out <slug>.your-zone to each customer cannot use per-hostname certificates: Let’s Encrypt allows 50 certificates per registered domain per week, and every new shop would wait for its own. A wildcard certificate covers all of them at once, so a shop that signed up a second ago is served over HTTPS immediately.

For a handful of hostnames, add them as custom domains instead.

Requirements

  • Your team hosts the zone on HostStack DNS (Dashboard → Domains → DNS), and the registry delegates it to HostStack’s nameservers. Delegation is checked when you create the certificate and again before every issuance — it is what proves the zone is yours.
  • zone is the hosted zone itself or a name inside it: shops.example.com in a hosted example.com covers *.shops.example.com.
  • The target is a web service or a static site.
  • If the zone has a CAA record, it must allow issuewild "letsencrypt.org".

Create one

bash
# The zone must be hosted on HostStack DNS and delegated to its nameservers.
hoststack wildcard-certs create shops.example --service svc_storefront
hoststack wildcard-certs status shops.example    # pending → active, usually under a minute
hoststack wildcard-certs list
typescript
const { wildcardCert } = await hs.wildcardCerts.create(teamId, {
  zone: 'shops.example',
  serviceId: 'svc_storefront',
  includeApex: false,
});
// Poll until wildcardCert.status === 'active'.

HostStack writes a *.your-zone A record pointing at its edge (an existing * record pointing elsewhere is refused rather than overwritten), orders the certificate, and answers the DNS-01 challenge on its own nameservers. With includeApex the bare zone is covered and routed too; if the apex already points somewhere else, that record is left alone and the response says so.

Routing

Request forServed by
A name with its own custom domain (vip.your-zone)That domain’s service — explicit domains always win
Any other <name>.your-zoneThe wildcard’s service
your-zone (apex)The wildcard’s service, only with includeApex
a.b.your-zoneNothing — not covered by the certificate

The Host header reaches your service unchanged. Read the tenant from it:

typescript
// One service answers every <slug>.shops.example. The Host header is untouched.
app.use(async (req, res, next) => {
  const host = req.headers.host?.split(':')[0] ?? '';
  const slug = host.endsWith('.shops.example') ? host.slice(0, -'.shops.example'.length) : null;
  req.tenant = slug ? await tenants.findBySlug(slug) : null;
  if (!req.tenant) return res.status(404).send('No such shop');
  next();
});

Once a zone has a wildcard, other teams can no longer attach names under it as custom domains.

Renewal and failures

  • Certificates are renewed 30 days before they expire. status stays active while a valid certificate is served, even if a renewal attempt failed — lastError and nextAttemptAt say what happened and when HostStack tries again.
  • A failure notifies your team’s channels and fires the service.acme_cert_failed webhook (with kind: "wildcard"), at most once a day per episode. Every successful issuance or renewal fires wildcard_cert.issued.
  • hoststack wildcard-certs renew <zone> (or renew_wildcard_cert) retries immediately after you fix the cause.

From an agent

MCP tools: create_wildcard_cert, get_wildcard_cert, list_wildcard_certs, update_wildcard_cert, renew_wildcard_cert, delete_wildcard_cert.

Next steps

Was this page helpful?