Domains and DNS validation

Verify domain ownership with a TXT record, then connect one of 217 DNS providers so DNS-01 challenges - and wildcard certificates - are solved automatically.

Every domain is verified once before it can be attached to a certificate. After that, connecting a DNS provider is optional. It is what unlocks DNS-01 validation, and with it wildcards and hosts that are not publicly reachable.

Verifying a domain

Add the domain under Manage > Domains. aethercert returns a TXT record to publish at your registrar or DNS host:

_aethercert-challenge.example.com.  TXT  "<verification token>"

Once it resolves, press Verify. The control plane resolves that exact name and compares the value; there is no waiting period beyond normal DNS propagation, and a failure says which of the two went wrong - no record at all, or a record that does not match.

This is a one-time step per domain, and it is separate from the ACME challenge that happens at issuance. It proves to aethercert that the domain is yours, so one organization cannot request certificates for another's names.

Domain names are globally unique

A domain can be registered by one organization at a time across the whole platform. Adding one that another organization already holds is refused, and that organization has to remove it first. This is what makes the verification above meaningful.

Internal domains

A domain that is not publicly resolvable can be marked internal when you add it. That skips TXT verification entirely - there is no public DNS to publish the record in, and the control plane could not resolve it either - and the domain is created already verified.

In exchange, an internal domain can only be used with an Internal CA (REST) authority. ACME challenges are not available for names the outside world cannot resolve.

Choosing a validation method

Certificates from a public authority are validated one of three ways.

	DNS-01	HTTP-01	TLS-ALPN-01
How control is proven	A TXT record under `_acme-challenge`	A token at `http://<host>/.well-known/acme-challenge/`	The TLS handshake answers with a challenge certificate
Needs a DNS provider connected	Yes	No	No
Host must be publicly reachable	No	Yes, on port 80	Yes, on port 443
Wildcards	Yes	No	No
Good for	Everything else - internal hosts, load-balanced names, wildcards	A public web server that already answers on port 80	A host with nothing already listening on 443

Internal REST authorities use none of these. They sign the CSR directly, so no challenge is involved at all.

HTTP-01 without a webroot binds port 80

If the certificate uses HTTP-01 and no webroot is configured on the deploy target, the agent binds port 80 itself for the duration of the challenge. On a host that already runs a web server there, set http01_webroot on the deploy target instead so both can coexist.

TLS-ALPN-01 always binds its own listener

TLS-ALPN-01 has no webroot equivalent. Proving control means the agent's own process answers the TLS handshake, which means owning port 443 for the duration of the challenge. Choose it for a host with nothing else terminating TLS on 443; otherwise use HTTP-01 with a webroot, or DNS-01.

Forwarding a non-standard port

If this host's firewall or NAT forwards the internet-facing port 80 or 443 to a different local port, set that local port on the agent (Manage > Agents > Edit, standalone challenge ports). The CA's validators always connect to the standard public port - this only changes where the agent binds locally.

Creating or editing a certificate that uses HTTP-01 or TLS-ALPN-01 checks upfront whether each of its hostnames is actually reachable on the challenge port from the public internet, and refuses the job with the exact reason if one is not, instead of letting it fail once dispatched. See Network requirements for the full list of what has to be reachable, from where and on which port.

Connecting a DNS provider

Connect a provider on the domain's own page under Manage > Domains. aethercert supports 217 DNS providers - the full lego provider set, matched one for one by the agent.

The list is searchable, and each entry states which credential it needs and where in that provider's console to create it. For most providers the credentials are tried against the real API before they are stored, so a token with the wrong scope fails when you paste it rather than at 3 a.m. during a renewal. A small number cannot be checked from the control plane at all - the exec provider runs a script on the agent host, for instance - and those are stored without a live check.

Providers with a step-by-step guide

Four of the most common carry their own hint text with the exact permission scopes:

Provider	Credential
Cloudflare	A custom API token with both `Zone:DNS:Edit` and `Zone:Zone:Read`, scoped to the zone. Zone:Read is what looks the zone ID up before DNS:Edit can create the record; a token with only Edit fails.
AWS Route 53	An IAM user or role scoped to `route53:ChangeResourceRecordSets` on the hosted zone. Optionally pin the hosted zone ID.
DigitalOcean	A personal access token with write scope, from API > Tokens.
Hetzner DNS	An API token from the Hetzner DNS Console, under API Tokens.

Everything else

The other 213 follow the same pattern: pick the provider, read its hint, paste the credential, save. A representative selection of what is in the list:

Category	Providers
Hyperscalers	Azure DNS, Google Cloud DNS, AWS Route 53 and Lightsail, Oracle Cloud Infrastructure DNS, Alibaba Cloud DNS, Tencent Cloud DNS, Huawei Cloud DNS, IBM Cloud, Open Telekom Cloud
Managed DNS	Akamai EdgeDNS, NS1, UltraDNS, DNS Made Easy, Constellix, Gcore, Bunny.net, DNSimple, LuaDNS, ClouDNS, deSEC
Hosting and VPS	Linode, Vultr, Scaleway, Exoscale, Hetzner, netcup, OVHcloud, Infomaniak, GleSYS, Leaseweb
Registrars	GoDaddy, Namecheap, Name.com, Porkbun, Gandi, INWX, united-domains, Joker.com, NameSilo, Spaceship
Panels and self-hosted	PowerDNS, Technitium, Plesk, cPanel/WHM, ISPConfig, Infoblox, BlueCat, EfficientIP, VinylDNS, OpenStack Designate
Platforms	Vercel, Netlify, Cloudflare, Azion, StackPath, F5 Distributed Cloud
Dynamic DNS	DuckDNS, Dynu, deSEC, DynDNSFree.de, dnsHome.de, freemyip.com, IPv64.net, myaddr.tools
Escape hatches	ACME-DNS (`acmedns`), a generic webhook (`httpreq`), or a script on the agent host (`exec`)

If your provider is not in the list, the last row is the answer. ACME-DNS delegates _acme-challenge to a purpose-built server, the generic webhook posts the record to an endpoint you control, and exec runs a script that is already on the agent host. Between them, anything with an API can be automated.

How credentials are handled


Storage	Encrypted in Supabase Vault, not in the domain row.
Read-back	Never. Once saved, a credential is not returned to the browser again - editing a domain shows an empty field, and leaving it empty keeps the stored value.
Use	The agent fetches short-lived credentials from the control plane at the moment a challenge is being solved. They are not stored on the agent host.
Validation	Tried against the provider's real API before saving, where a live check is possible.

Scope the credential to the single zone aethercert needs wherever the provider supports it. An account-wide token is a larger blast radius for no benefit.

Practical notes

One domain, many certificates. Verify example.com once and every certificate for it and its subdomains can use it. You do not add a domain per hostname.
Subdomain delegation works. If internal.example.com is delegated to a different DNS zone, add it as its own domain with its own provider credentials.
Changing DNS provider means replacing the credentials on the domain. Existing certificates are unaffected; the new credentials are used from the next challenge on.
Removing a provider leaves the domain verified but drops it back to HTTP-01 or TLS-ALPN-01, which breaks renewals for any wildcard certificate on it.

Auf dieser Seite