Skip to main content

Zones

A zone binds a DNS apex to a credential. You select the zone explicitly on a certificate request that uses automated DNS-01; CertAutoPilot then uses that zone's credential to publish the _acme-challenge TXT record.

The zone model​

Each zone has:

  • Domain — example.com, internal.example, etc.
  • Credential — one of the project's configured DNS credentials.
  • Optional description.

Zones are project-scoped, and a zone's credential must belong to the same project.

Choosing the zone​

The zone is chosen explicitly on the certificate request (zone_id) — CertAutoPilot does not infer it from the certificate's domains and does no longest-suffix matching. Register one zone per credential/sub-tree and pick the right one when you create the certificate.

This is what lets different sub-trees of one apex use different providers: register them as separate zones and select whichever the certificate needs.

ZoneCredentialSelect it for
example.comcloudflare-prodwww.example.com, api.example.com
internal.example.comroute53-internaldb.internal.example.com

CNAME aliasing​

Common pattern when the production zone is locked down (regulated, or owned by another team): publish a CNAME at _acme-challenge.api.example.com pointing to _acme-challenge.api.acme.example.org, where acme.example.org is a zone CertAutoPilot can write to. The CA follows the CNAME and validates the record where it lives.

; Once, manually, in the production zone:
_acme-challenge.api.example.com.  CNAME  _acme-challenge.api.acme.example.org.

No configuration is needed in CertAutoPilot — there is no "challenge override" field. The challenge FQDN is resolved through the CNAME automatically, so the record is written in the delegated zone. Register that delegated zone (acme.example.org) with its credential and select it on the certificate.

What is checked on save​

Creating a zone validates three things:

  1. The domain is non-empty and has no leading or trailing dot.
  2. The selected DNS credential exists and belongs to the same project.
  3. For a Windows DNS (WinRM) credential only: the zone domain must be equal to or under the credential's configured DNS Zone, otherwise the request is rejected (422). The check is best-effort — if the credential's stored config cannot be decrypted it does not block, and the issuance-time check still guards.

The domain format is not otherwise constrained: there is no Public Suffix List enforcement, so registering a public-suffix name is not blocked.

No probe record is written on save. To verify that the credential can actually create records, use the credential's Test button with a domain — that writes and immediately deletes a throw-away TXT record. See DNS providers.

API​

GET    /api/v1/projects/{project}/zones
POST   /api/v1/projects/{project}/zones            (project admin)
GET    /api/v1/projects/{project}/zones/{id}
PATCH  /api/v1/projects/{project}/zones/{id}       (project admin)
DELETE /api/v1/projects/{project}/zones/{id}       (project admin)
GET    /api/v1/projects/{project}/zones/{id}/certificates
GET    /api/v1/projects/{project}/zones/{id}/rate-limits

See also​