DNS Credential Sets
Stores the DNS-provider API access mipo uses to answer the Let's Encrypt DNS-01 challenge. A set holds the provider, its non-secret fields and its secrets, which are encrypted and never shown again. Certificate profiles reference a set by name; a set that a profile uses cannot be deleted. Testing a set is read-only — it never creates or changes a DNS record.
Inputs
| Name | Description | Allowed values | Default |
|---|---|---|---|
Name | How the set is listed on certificate profiles | Unique text | — |
DNS Provider | Which provider API to call. Fixed once the set exists — create a new set to switch providers | Cloudflare, DuckDNS, DigitalOcean, Hetzner, deSEC or Namecheap | Cloudflare |
Provider credential fields | The API token, key, username or whitelisted IP the provider needs. Password fields are encrypted; leaving one blank on edit keeps the stored value | Provider-specific; see the help text under each field | — |
Hostname to test | The Test button asks the provider which zone owns this name, read-only. Leave blank to use a profile's hostname; before any profile exists, enter the host you are going to certify | FQDN | First hostname of a referencing profile |
Fields & columns
| Name | Description |
|---|---|
Provider | The DNS provider this set authenticates against |
Public fields | The non-secret provider fields (for example a Namecheap API username and whitelisted IP), shown in full |
Secrets | "Set" plus the date the secrets were last replaced. The values themselves are never returned by the API |
Last test | verified, unverified or failed, from the last read-only Test — or "Never tested" |
Used by | How many certificate profiles reference this set. Delete is disabled while this is not zero |
How to
Add a credential set and prove it works
- Click "Add DNS Credential Set".
- Give it a name you will recognise on a certificate profile, for example cloudflare-main.
- Choose the DNS provider. The credential fields below change to match it.
- Paste the provider credentials. Every field marked with an asterisk is required.
- Optionally set a test hostname — a name in the zone the provider serves.
- Save, then click Test on the new row. Test is read-only: it reads the zone and never writes a record.
- A "verified" result means a certificate profile can use this set.
Rotate a provider credential
- Click Edit on the set.
- Type the new secret into the password field. Leaving it blank keeps the stored value, so only fill in what actually changed.
- Save. The set's last test result is cleared, because the stored credential is no longer the one that was tested.
- Click Test to prove the new credential before the next renewal needs it.
Replace a set that is in use
- Delete is disabled while a certificate profile references the set — the "Used by" column shows how many.
- Open Certificate Profiles and point each listed profile at a different set, or delete the profile.
- Come back and delete the set once "Used by" reads "Not used".
Gotchas
- Setting up TLS for the first time? Start on SSL Status. It saves and tests a new credential set in one click and moves on to the profile. This page is for editing or replacing credentials directly.
- Secrets are write-only. The API never returns them, so a password field always starts empty — blank means "keep what is stored", not "clear it".
- The DNS provider is fixed once the set exists. Switching providers means creating a new set and repointing the profiles.
- Namecheap has no single-record API, so each issuance reads the whole zone and writes it all back. The pre-change zone is saved to the HTTP exchange journal at /data/config/acme-http-journal/<run>/ before anything is written — that folder is the restore copy.
- If Namecheap ever writes the zone back lossy (a record missing after our write), the issuance fails and the zone is repaired on the spot: every record that existed before the write is restored, anything added meanwhile is kept, only our challenge record is removed. A single-value record (CNAME) that someone re-pointed during those seconds keeps its new value and is listed as a conflict. The dns-zone-divergent alarm opens with the details and resolves on the next lossless write to that zone.
- Test never writes a DNS record, so a verified result proves read access and the account shape, not that a challenge record can be created.
- Hetzner issuance stays refused until a live-zone round trip has been validated, even with a verified credential set.
- Changing any secret clears the last test result on purpose: the recorded result belonged to the previous credential.
API calls (5)
| Method | Path | Description |
|---|---|---|
| GET | /api/admin/ssl/dns-credential-sets | List the credential sets with their test state and usage |
| POST | /api/admin/ssl/dns-credential-sets | Create a credential set |
| PUT | /api/admin/ssl/dns-credential-sets/:id | Update a set. A blank secret keeps the stored value |
| DELETE | /api/admin/ssl/dns-credential-sets/:id | Delete a set that no certificate profile references |
| POST | /api/admin/ssl/dns-credential-sets/:id/test | Run a read-only provider check and record the redacted result |
Related
- Certificate Profiles — A profile names the credential set used for its DNS-01 challenge
- SSL Status — The guided path: adds and tests a credential set as its second step, then carries it through to a served certificate