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.
zoneis the hosted zone itself or a name inside it:shops.example.comin a hostedexample.comcovers*.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
# 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 listconst { 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 for | Served by |
|---|---|
| A name with its own custom domain (vip.your-zone) | That domain’s service — explicit domains always win |
| Any other <name>.your-zone | The wildcard’s service |
| your-zone (apex) | The wildcard’s service, only with includeApex |
| a.b.your-zone | Nothing — not covered by the certificate |
The Host header reaches your service unchanged. Read the tenant from it:
// 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.
statusstaysactivewhile a valid certificate is served, even if a renewal attempt failed —lastErrorandnextAttemptAtsay what happened and when HostStack tries again. - A failure notifies your team’s channels and fires the
service.acme_cert_failedwebhook (withkind: "wildcard"), at most once a day per episode. Every successful issuance or renewal fireswildcard_cert.issued. hoststack wildcard-certs renew <zone>(orrenew_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?