Delegated DNS-01 (dashboard)¶

For native Agent setup and challenge ownership, see Agent workflow usage.

Let CertIntel answer the ACME dns-01 challenge for a hostname you control, without giving your ACME client write access to your real DNS zone. You create a record, add one CNAME, and point your ACME client's update credential at it - CertIntel's authoritative DNS service answers the challenge from then on.

This page covers creating and managing a delegation record from the dashboard. For using it in a native CertIntel Agent workflow, see Delegated DNS-01 in the Agent. Other ACME clients can use the CertIntel plugins for simple-acme, win-acme, Posh-ACME, Certbot and acme.sh, the native API (PUT /api/v1/dns-delegations/{id}/txt), or the built-in acme-dns-compatible shim; the DNS setup below is the same. The Agent does not expose its provider as a general-purpose validation script hook.

Creating a record¶

Get a certificate for a server on the dashboard's Overview creates the records a certificate needs (one per name), shows the CNAME to add for each with a Check DNS button, and checks that every CNAME resolves before it proposes the certificate to the server. If you already use certbot, acme.sh, Posh-ACME or another ACME client, you need no Agent: the introduction of Get a certificate for a server links to Delegated DNS-01 with the new-record form open (/dns-delegations?create=1), and the page shown after creating the record gives each client its configuration (see Pointing your ACME client at it). You can also create a record by hand:

On Delegated DNS-01 → New delegation record, enter the domain name you want validated (e.g. shop.example.com) and pick a child organization (the one selected in the top bar, or the only one you can choose, is pre-selected). CertIntel generates a random 32-character subdomain under its own zone and a one-time update secret, then shows you the exact DNS record to add:

_acme-challenge.shop.example.com.  CNAME  <random-subdomain>.dns01.certin.tel.

Copy buttons are provided for both the record name and the value, so you can paste them straight into your DNS provider without retyping. Most DNS providers' forms take the record name relative to the zone and add the zone themselves: CertIntel finds the name's zone in DNS (walking up from the name, the first name that is a zone of its own) and, for a name at its zone or directly below it, also shows that short form with its own Copy button (If your DNS provider adds the zone example.com itself (most do), enter only: _acme-challenge.shop). For a name further below its zone, or when it cannot read the zone, it guesses no value, because your provider may show a zone in between: it says to enter only the part before your zone's name, as your provider shows it next to the field (for _acme-challenge.web.shop.example.com in the zone shop.example.com, that is _acme-challenge.web). Get a certificate for a server shows the same. Use the generated label verbatim: CertIntel's DNS answers only for labels of exactly that shape, so a shortened or altered target never resolves.

One record covers both the base domain and its wildcard - shop.example.com and *.shop.example.com both resolve the ACME challenge from the same _acme-challenge.shop.example.com name, so you never need a second CNAME for the wildcard.

The address /dns-delegations?create=1 opens the Delegated DNS-01 page with the New delegation record form already open; links from elsewhere in the dashboard use it.

Pointing your ACME client at it¶

The page that shows the new record's secret, and later the record's own page, has a Use this delegation with… card. It lists the four values every client needs - Delegation ID, CNAME target, API base (the right address for your workspace on this deployment) and Update secret - and one section per client with its configuration filled in, ready to copy:

The secret appears in the blocks only on the page that shows it once; the record's own page shows YOUR-DELEGATION-SECRET in its place (Rotate secret gives a new one).

For simple-acme, win-acme, Posh-ACME, Certbot or acme.sh, install the plugin from the corresponding plugin installation guide. Each plugin uses the Delegation ID, CNAME target, API base and update secret. The native DLL and Posh-ACME plugins save credentials through the client; Certbot uses a private JSON mapping file; acme.sh saves the CERTINTEL_* settings in its account configuration.

CertIntel speaks the acme-dns update protocol, so most ACME clients with an acme-dns plugin (cert-manager, lego, acme.sh, certbot-dns-acmedns, and others) work directly. Only POST /acme-dns/update is implemented; /acme-dns/register answers 403 (registration is disabled; create a Delegated DNS-01 record in the CertIntel …) on every address that serves /acme-dns/update, on purpose, because registration is what you did on the dashboard when you created the record. Fill the client's acme-dns account from the record's detail page:

Or use the native API directly:

curl -X PUT https://<update-base>/api/v1/dns-delegations/<id>/txt \
  -H "X-Api-Key: <secret>" \
  -H "Content-Type: application/json" \
  -d '{"values": ["<acme-challenge-value>"]}'

Up to two TXT values are kept live at once on the same name, so an apex + wildcard pair validating in the same run doesn't clobber either value; a request with more than two values is rejected. Updates are accepted only from the update secret; an Agent's own API key does not authenticate them (see Delegated DNS-01 in the Agent).

GET (and PUT) on …/dns-delegations/<id>/txt answer with the record's subdomain, its current values and its cname_target, the full CNAME destination (null on a deployment without a delegation zone):

{
  "subdomain": "k7q2m4x6z3b3n5p7r6t2v4w6y5c3d5f7",
  "values": [],
  "cname_target": "k7q2m4x6z3b3n5p7r6t2v4w6y5c3d5f7.dns01.certin.tel"
}

The CertIntel Agent uses cname_target to check a delegation, so it needs no CNAME destination typed in (Agent 1.8.0+).

A tenant administrator can switch TXT updates off for the whole workspace on Settings → Security under What your agents may submit (DNS-01 challenge updates, covering both /acme-dns/update and the native txt route); the records and their CNAMEs stay in place, only updates are refused until it is turned back on.

A TXT value is at most 255 characters of ASCII (an ACME challenge value is base64url); anything longer, or with other characters, is refused - 422 from the native API, 400 from /acme-dns/update - instead of being stored and breaking the record's DNS answer. A value set more than two hours ago is no longer served, returned or kept on the next update, so a value a client failed to clean up stops blocking new challenges on its own. Reading the record (GET …/txt) has its own rate limit, separate from updates, and a rate-limited request answers 429 with a Retry-After header saying how long to wait.

CAA records¶

Each domain on the Delegated DNS-01 list shows a CAA line under its name: CAA: any CA, only <issuer names> (with wildcards: … when issuewild differs), every CA refused (critical record), not applicable or CAA lookup failed; hover it for where the deciding records were found. A record's page has a CAA records card: the records that decide for the domain and its wildcard (or that there are none, so any CA may issue), and for each ACME account of the organization you can see, whether its CA may issue, with the exact record to add when it may not. Without such an account the card checks Let's Encrypt, labelled the default CA. See CAA records for how the check reads the records.

Managing a record¶

• Rotate secret issues a new update secret; the old one stops working immediately. The record's id, subdomain, and CNAME target don't change, so you don't need to touch DNS again.
• Revoke stops the record answering (and stops accepting new TXT updates) without deleting it; Reactivate brings it back.
• Delete removes the record permanently.
• CNAME check: the list and the record's page say whether _acme-challenge.<name> in public DNS points at the record's CNAME target - CNAME OK, CNAME points elsewhere, CNAME missing or Check failed (the lookup failed; retried automatically) - and, for a problem, the exact record to change or add in your DNS zone. CertIntel checks through public resolvers: a new record a few minutes after it is created (every 5 minutes during its first hour while the CNAME is missing, points elsewhere or cannot be looked up), whenever its page is opened, when an Agent reports a certificate issued for one of its names (also when installing it then failed) while its last check was not CNAME OK, and every few hours afterwards. Until then the page says Not checked yet: add the CNAME below at your DNS provider, then Check now. Check CNAMEs now (list) and Check now (record) check at once. A CNAME that points at the target of another of the organization's records names that record (… the target of the record for …: a copy-paste mix-up?). A record whose CNAME is missing or points elsewhere is listed under Needs attention on the Overview. See DNS-01 validation fails with a delegated record.

Native Agent workflows store the delegation's scoped update secret in the local protected secret store. Use Edit workflow… → DNS delegations (Windows) or the terminal interface's Settings screen (Linux) to test or replace it after a dashboard rotation.

Rotating or revoking the update secret never affects the CNAME your DNS zone already publishes - only the credential used to update the TXT value changes.

The record's Recent updates table lists each TXT change. From is the address CertIntel received the update from: behind NAT or a proxy it is the address of that NAT device or proxy, not the server's own.