ACME DNS-01 certificates with PrimeDNS
The DNS-01 challenge lets you issue Let's Encrypt certificates, including wildcards (*.domain.tld),
without exposing port 80/443. Your ACME client asks PrimeDNS to create a _acme-challenge TXT
record, Let's Encrypt verifies it over DNS, and the client removes it again.
Choose your client
- acme.sh: a shell ACME client, with a PrimeDNS DNS API plugin.
- certbot: with two small hook scripts.
- lego and Traefik: with the PrimeDNS provider built into lego.
- cert-manager on Kubernetes: with the PrimeDNS webhook.
Any other client that can call an HTTP API or run a hook can use the same endpoint, see Calling the API directly. Every client needs the same thing first: an API key.
Create an API key
Go to Account → API Keys and create
a key for ACME. Choose Certificate key and list in the hostnames field each hostname you will issue a certificate for
(one per line, for example domain.tld and api.domain.tld) and untick the other scopes.
Such a key gets one acme:name:_acme-challenge.<hostname> scope per name and can only create and remove the
_acme-challenge TXT record for exactly those names, so a key that leaks from a server cannot change any of
your records or validate any other name. domain.tld also covers *.domain.tld (both validate at
the same name), but not api.domain.tld. (Keys with dns:write also work.)

Wildcard certificates
A wildcard certificate (*.domain.tld) can only be issued with the DNS-01 challenge:
Let's Encrypt states that "wildcard issuance must use the DNS-01 challenge". HTTP-01 cannot
validate a wildcard, so this is the one case where DNS-01 is not just a convenience.
- One level.
*.domain.tldmatcheswww.domain.tld, but nota.b.domain.tldand notdomain.tlditself (RFC 6125, section 6.4.3). - Ask for both names when you need the bare domain too:
-d domain.tld -d '*.domain.tld', as in the examples on the client pages. - Two TXT values, one name. Each of the two names is validated separately, so the CA
expects two different values at
_acme-challenge.domain.tldat the same time. PrimeDNS accepts several values under one name.
CNAME delegation: certificates for a domain hosted elsewhere
The simplest setup is the one above: the domain's DNS is on PrimeDNS, and the API key above is all you need. If a domain's DNS stays with another provider, for example one without an API, PrimeDNS can still answer the challenge for it. One record at the other provider forwards the challenge to a zone you host with us, and your ACME client writes the validation record there.
An example
You want a certificate for shop.example.com, whose DNS is at another provider. In your PrimeDNS account you
have the zone example.net, which will receive the validation records.
| Where | Record | Who creates it | How long |
|---|---|---|---|
| At the other provider (zone example.com) |
_acme-challenge.shop.example.com CNAME validation.example.net. |
You, once, by hand | Stays; used for every renewal |
| PrimeDNS (zone example.net) |
validation.example.net TXT "<token from the CA>" |
The PrimeDNS API, when your ACME client asks for it | Seconds to minutes: removed right after validation |
validation.example.net does not have to exist beforehand; the TXT record creates it. The two domains do not
have to be related, and the CNAME is the only thing you add by hand.
Set it up
- Pick the target zone. Any zone of your PrimeDNS account will do (here
example.net), and its nameservers must point to PrimeDNS. A name in somebody else's zone, or in a zone hosted at another provider, cannot be used. - Create a key. In Account → API Keys
choose Certificate key and leave hostnames empty. Under CNAME delegation targets enter
validation.example.net. The key gets the scopeacme:name:validation.example.net: it can add and remove TXT records at exactly that name and nowhere else. - Add the CNAME at the other provider:
_acme-challenge.shop.example.compointing tovalidation.example.net. - Run your ACME client with that key as
PRIMEDNS_API_KEY, asking for a certificate forshop.example.com. The client has to know where the CNAME leads, so it can call the PrimeDNS API with the namevalidation.example.net. How you tell it depends on the client, see the table below.
What happens when the certificate is issued
- Your client asks the CA (Let's Encrypt or another) for a certificate for
shop.example.com. The CA answers with a token to publish in DNS. - The client calls the PrimeDNS API. PrimeDNS creates the TXT record at
validation.example.net. - The client waits a moment for the record to be served.
- The CA looks up
_acme-challenge.shop.example.com. The other provider answers with the CNAME, the CA follows it tovalidation.example.netand gets the TXT record from the PrimeDNS nameservers. The token matches, so the domain is verified. - The client calls the API again and the TXT record is removed. The CNAME stays for the next renewal.
If you ask for both shop.example.com and *.shop.example.com, both are checked at the same
name, so two TXT records sit at validation.example.net at once. PrimeDNS accepts that, and each one is
removed separately.
The target and your client
You can point the CNAME at the validation name in two forms. Both work; pick the one your client expects.
| CNAME points to | Key scope (from the key form) | acme.sh | cert-manager |
|---|---|---|---|
validation.example.net |
acme:name:validation.example.net, from the CNAME delegation targets field |
--domain-alias validation.example.net |
cnameStrategy: Follow |
_acme-challenge.validation.example.net |
acme:name:_acme-challenge.validation.example.net, list validation.example.net under hostnames |
--challenge-alias validation.example.net |
cnameStrategy: Follow |
acme.sh needs the alias option on the command line, see acme.sh. cert-manager follows the CNAME
when the solver has cnameStrategy: Follow, see cert-manager. The certbot hook scripts
write the record for the domain you pass to certbot, so use acme.sh or cert-manager for a domain whose DNS is elsewhere.
Calling the API directly
An ACME client or a script sends the full name of the TXT record to the API (that is what the plugins, hooks and the cert-manager webhook do). By hand it looks like this:
curl -X POST https://api.primedns.net/v1/dns/acme-challenge \
-H "X-API-Key: $PRIMEDNS_API_KEY" -H "Content-Type: application/json" \
-d '{"name": "_acme-challenge.shop.example.com", "value": "<token from the CA>"}'
curl -X DELETE https://api.primedns.net/v1/dns/acme-challenge \
-H "X-API-Key: $PRIMEDNS_API_KEY" -H "Content-Type: application/json" \
-d '{"name": "_acme-challenge.shop.example.com", "value": "<token from the CA>"}'
name is always the exact name of the TXT record: _acme-challenge.<hostname> for a
certificate for <hostname> (also for its wildcard), or the CNAME target (for example
validation.example.net) with a delegation. Removing a record needs its value, so other TXT
records at the same name are never touched.
Troubleshooting
DOMAIN_NOT_FOUND: the domain is not in your PrimeDNS account, or the API key belongs to a different account or team.403:INSUFFICIENT_SCOPEmeans the key has noacme:name:<fqdn>scope (ordns:write).NAME_NOT_ALLOWEDmeans the key is limited to other names; create a key that lists this one.- The CA reports
NXDOMAIN looking up TXT for _acme-challenge...although the record was added: a resolver that looked that name up just before (a propagation check of your client, a manualdigor an earlier attempt) is still holding the "does not exist" answer. Our name servers drop it when the record is created, but a resolver you use may keep it for up to a minute (the SOA minimum of your zone). Wait a little and retry, and avoid querying the name yourself before the run. 422:nameorvalueis missing from the request, ordomainwas sent instead ofname. Check that your client or hook passes the full record name and the token.