How do I configure DNS provider credentials, and what are the common per-provider gotchas?

[fabriziosalmi]

I am setting up a DNS provider in CertMate for the first time. The form asks for a token / key / file, and the docs list a different credential format for every provider. Where do I get the credential, what scope does it need, and which providers have non-obvious quirks I should know about before I file a "DNS auth failed" issue?

[fabriziosalmi]

The full per-provider table is in the wiki: DNS Providers. Below is the high-signal subset — the gotchas that account for the majority of "I cannot get DNS auth working" issues filed against CertMate.

Cloudflare. Use an API Token, not the old Global API Key. Scopes the token needs: Zone:Zone:Read (to list zones) and Zone:DNS:Edit (to write the TXT record), restricted to the specific zone you want CertMate to manage. The "include all zones" form is more permissive than you usually want. Symptom of wrong scope: "1003 — Invalid request" from certbot. (#59)

AWS Route53. The IAM policy needs route53:ListHostedZones, route53:GetChange, and route53:ChangeResourceRecordSets scoped to the hosted-zone ARN. Common pitfall: an IAM user with policies attached and an attached SCP that denies route53:ChangeResourceRecordSets at the org level — the deny wins, the SCP is rarely visible in the IAM console, the error message is generic. (#75, #112)

Azure DNS. Use a service principal with DNS Zone Contributor on the specific zone. Confusion comes from the two Azure plugins: certbot-dns-azure was the original; newer Azure SDK versions have a different flag layout. Issue #113 caused an "Ambiguous --dns-azure" message because two plugins registered the same flag prefix; PR #119 fixed it by selecting via --authenticator explicitly. If you are on a release older than the fix, the workaround is to uninstall the conflicting plugin.

Hetzner. Two separate plugins, two separate credentials: certbot-dns-hetzner for the legacy DNS API and certbot-dns-hetzner-cloud for the newer Cloud-API DNS. The settings UI exposes them as two different providers. If your token works in the dashboard but CertMate says "auth failed", you probably picked the wrong one. (#95)

Akamai Edge DNS. The credential is an .edgerc-style block with client_token, client_secret, access_token, and host. Common confusion: people enter just the access token. The plugin used is certbot-plugin-edgedns (not certbot-dns-akamai), which is why "Akamai" sometimes appears missing — older releases hid it because the plugin was not installed by default. PR #119 + #136 made it explicit. (#99, #116)

RFC2136 (BIND / nsupdate). The credential is a TSIG key with its name, algorithm, and secret. The rfc2136.ini is generated by CertMate from those fields; if you upgrade and the file is missing, it is regenerated on first save. (#82, #85) Make sure the BIND server allows updates from the CertMate host's IP and that the TSIG name matches what BIND has configured (including the trailing dot).

ACME-DNS. A delegation server. Setup is two-step: register an account on the ACME-DNS server (one HTTP POST), then point _acme-challenge.<domain> at the returned hostname via CNAME. This is the only DNS provider where the "credential" includes a per-domain registration, not just a global token. (#29)

Multi-account. Every major provider supports multiple accounts: production token, staging token, disaster-recovery token. Each certificate is bound to one account. Useful for blast-radius isolation: a leaked staging token cannot rotate the production cert.

Diagnose "DNS auth failed". The audit log entry for the failed issuance carries the certbot stderr verbatim. That message — not the toast — is what tells you whether the credential is wrong, the zone is wrong, or the propagation timed out. /api/activity and the Recent Executions widget both surface it.