Reference

Dns01 API

12 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/dns/credentials

List DNS provider credentials

Needs proxy:write. Secret variables are never returned; non-secret ones (an access key ID, a region) only to administrators.

Parameter	In	Type	Description
`serverId`	query	string (uuid)	Only the team-wide credentials and this server's

Response 200 · OK · application/json

CredentialsOutputBody

DNSCredential[] | nullrequired

Errors

401Unauthorized
403Forbidden
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/dns/credentials

Add a DNS provider credential

Needs admin. The values are sealed with the instance secret key and delivered to the proxy container as environment variables at deploy time; they are never part of a stored payload and never returned. 422 invalid_credential / invalid_provider, 409 credential_name_taken.

Request body · application/json · required

CreateCredentialInputBody

namestringrequired
Unique per team
providerstringrequired
The lego provider code: one of GET /dns/providers or GET /dns/lego-providers
serverIdstring
Scope the credential to one server; omit for the whole team
map of stringrequired
Provider variables by name (see GET /dns/providers and GET /dns/lego-providers). Write-only: sealed at rest, never returned.

Response 201 · Created · application/json

DNSCredential

createdAtstring (date-time)required
DNSCredentialField[] | nullrequired
idstringrequired
namestringrequired
providerstringrequired
The lego provider code
providerNamestringrequired
revinteger (int64)required
Advances whenever the values change
scopeenum: team | serverrequired
team: usable on every server of the team; server: only on ServerID
serverIdstringrequired
updatedAtstring (date-time)required
DNSCredentialUse[] | nullrequired

Errors

401Unauthorized
403Forbidden
409Conflictcredential_name_taken
422Unprocessable Entityinvalid_credential
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/dns/credentials/{credentialId}

Rename a credential or rotate its values

Needs admin. Changed values stage a proxy deploy on every server whose resolver uses the credential (the proxy container is recreated with the new environment).

Parameter	In	Type	Description
`credentialId`required	path	string

Request body · application/json · required

UpdateCredentialInputBody

clearstring[] | null
Optional variables to remove
namestring
map of string
Replaces the named variables; an empty value keeps the stored one

Response 200 · OK · application/json

DNSCredential

createdAtstring (date-time)required
DNSCredentialField[] | nullrequired
idstringrequired
namestringrequired
providerstringrequired
The lego provider code
providerNamestringrequired
revinteger (int64)required
Advances whenever the values change
scopeenum: team | serverrequired
team: usable on every server of the team; server: only on ServerID
serverIdstringrequired
updatedAtstring (date-time)required
DNSCredentialUse[] | nullrequired

Errors

401Unauthorized
403Forbidden
409Conflict
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/dns/credentials/{credentialId}

Delete a credential

Needs admin. 409 credential_in_use while a resolver (desired or applied) uses it.

Parameter	In	Type	Description
`credentialId`required	path	string

Response 204 · No Content

No body.

Errors

401Unauthorized
403Forbidden
409Conflictcredential_in_use
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/dns/lego-providers

Every other lego DNS provider, for the generic form

The providers of the lego release Traefik vendors that have no curated form: code, name, the lego docs link and the variables lego reads for it. A credential for one of them is a provider code plus variables from this list. exec and manual are not offered. Variables that read a file are left out.

Response 200 · OK · application/json

ProvidersOutputBody

PublicProviderBody[] | nullrequired

Errors

401Unauthorized
403Forbidden
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/dns/providers

Curated DNS-01 providers and their credential variables

Cloudflare, Amazon Route 53, Hetzner, DigitalOcean, Gandi, OVHcloud, Porkbun, Namecheap, Google Cloud DNS, Azure DNS, deSEC, Linode, Vultr, Scaleway, Bunny, DNSimple, IONOS, GoDaddy and Netcup. The variable names are the ones Traefik's ACME client (lego v5) reads. Any other lego provider is in GET /dns/lego-providers.

Response 200 · OK · application/json

ProvidersOutputBody1

DNSProviderSpec[] | nullrequired

Errors

401Unauthorized
403Forbidden
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/dns01/wildcards/{wildcardId}

Stage a change of a wildcard certificate's options

Parameter	In	Type	Description
`wildcardId`required	path	string

Request body · application/json · required

UpdateWildcardInputBody

coverGeneratedboolean
defaultboolean
includeApexboolean

Response 200 · OK · application/json

ServerDNS01

acmeEmailstringrequired
baseDomainstringrequired
The domain generated hostnames live under (the server's base domain)
DNSResolverView[] | nullrequired
stagedbooleanrequired
Staged DNS-01 changes await Deploy proxy
WildcardCertView[] | nullrequired

Errors

401Unauthorized
403Forbidden
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/dns01/wildcards/{wildcardId}

Stage the removal of a wildcard certificate

Parameter	In	Type	Description
`wildcardId`required	path	string

Response 200 · OK · application/json

ServerDNS01

acmeEmailstringrequired
baseDomainstringrequired
The domain generated hostnames live under (the server's base domain)
DNSResolverView[] | nullrequired
stagedbooleanrequired
Staged DNS-01 changes await Deploy proxy
WildcardCertView[] | nullrequired

Errors

401Unauthorized
403Forbidden
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/servers/{serverId}/dns01

A server's DNS-01 resolvers and wildcard certificates

Desired state with staged additions, updates and removals marked; certificate status and expiry are observed by the agent.

Parameter	In	Type	Description
`serverId`required	path	string

Response 200 · OK · application/json

ServerDNS01

acmeEmailstringrequired
baseDomainstringrequired
The domain generated hostnames live under (the server's base domain)
DNSResolverView[] | nullrequired
stagedbooleanrequired
Staged DNS-01 changes await Deploy proxy
WildcardCertView[] | nullrequired

Errors

401Unauthorized
403Forbidden
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PUT/servers/{serverId}/dns01/resolvers/{provider}

Stage the DNS-01 resolver of a provider on a server

Needs proxy:write. One resolver per provider and server. Staged until POST /servers/{id}/proxy/deploy, which recreates the proxy container. 422 acme_email_required, invalid_credential, agent_too_old.

Parameter	In	Type	Description
`serverId`required	path	string
`provider`required	path	string

Request body · application/json · required

SetResolverInputBody

credentialIdstringrequired
delaySecondsinteger (int64)
Wait before checking that the TXT record propagated (slow DNS providers)
stagingboolean
Use the Let's Encrypt staging CA (untrusted certificates, generous rate limits)

Response 200 · OK · application/json

ServerDNS01

acmeEmailstringrequired
baseDomainstringrequired
The domain generated hostnames live under (the server's base domain)
DNSResolverView[] | nullrequired
stagedbooleanrequired
Staged DNS-01 changes await Deploy proxy
WildcardCertView[] | nullrequired

Errors

401Unauthorized
403Forbidden
422Unprocessable Entityacme_email_required
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/servers/{serverId}/dns01/resolvers/{provider}

Stage the removal of a resolver

409 resolver_in_use while a wildcard certificate or a domain of a service on the server uses it.

Parameter	In	Type	Description
`serverId`required	path	string
`provider`required	path	string

Response 200 · OK · application/json

ServerDNS01

acmeEmailstringrequired
baseDomainstringrequired
The domain generated hostnames live under (the server's base domain)
DNSResolverView[] | nullrequired
stagedbooleanrequired
Staged DNS-01 changes await Deploy proxy
WildcardCertView[] | nullrequired

Errors

401Unauthorized
403Forbidden
409Conflictresolver_in_use
422Unprocessable Entity
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/servers/{serverId}/dns01/wildcards

Stage a wildcard certificate

Needs proxy:write and the provider's resolver on the server (422 resolver_not_configured). The certificate covers *.<domain> (and the apex with includeApex); coverGenerated lets generated domains use it; default makes it the proxy's default certificate. 409 wildcard_exists.

Parameter	In	Type	Description
`serverId`required	path	string

Request body · application/json · required

CreateWildcardInputBody

coverGeneratedboolean
Generated domains under the base domain use this certificate
defaultboolean
Make it the proxy's default certificate
domainstringrequired
Base domain; the certificate covers *.<domain>
includeApexbooleanrequired
Also cover the base domain itself
providerstringrequired

Response 201 · Created · application/json

ServerDNS01

acmeEmailstringrequired
baseDomainstringrequired
The domain generated hostnames live under (the server's base domain)
DNSResolverView[] | nullrequired
stagedbooleanrequired
Staged DNS-01 changes await Deploy proxy
WildcardCertView[] | nullrequired

Errors

401Unauthorized
403Forbidden
409Conflictwildcard_exists
422Unprocessable Entityresolver_not_configured
500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.