Delegated DCV and domain ownership

Why AutoCertify requires two records

A certificate authority needs proof that the requester controls a hostname. AutoCertify uses delegated Domain Control Validation (DCV): a CNAME at _acme-challenge.<hostname> points to the Cloudflare validation target returned for the domain. Cloudflare can answer validation challenges behind that delegation.

AutoCertify also needs to establish which workspace controls the hostname. A separate TXT record at _autocertify-verify.<hostname> carries a random ownership token associated with your domain in your workspace. Verification succeeds only when both records match. A CNAME left by another workspace cannot establish your ownership.

Get the exact records

Creating a domain returns the CNAME under validation.delegation and the TXT record under validation.ownership. You can retrieve them again with the request below. Use the token, hostname and domain ID saved in the quickstart.

curl --fail-with-body --silent --show-error \
  https://api.autocertify.net/v1/domains/$AUTOCERTIFY_DOMAIN_ID/delegation-record \
  -H "Authorization: Bearer $AUTOCERTIFY_TOKEN" \
  --output autocertify-dns.json

# The response has CNAME fields at the top level and a nested ownership TXT.
jq -r '[., .ownership][] |
  [.type, .host, .value, (.ttl | tostring)] | @tsv' autocertify-dns.json

This endpoint returns the CNAME’s type, host, value and ttl at the top level, plus a nested ownership object with the same four fields for the TXT record. Publish the values from your response exactly.

Keep both records in place while the hostname is managed. The delegation is designed to remain in place across renewals. DNS changes, a workspace move or a change to the service’s validation configuration can require updated records; use the current API response when troubleshooting.

Enter the host correctly at your DNS provider

Edit records at the provider named by your domain’s authoritative nameservers, which may be different from the registrar where you bought the domain. Some providers accept fully qualified names; others append the DNS zone automatically. In a zone named example.com:

These are host-field examples only. Use your returned delegation target and ownership token for the values. Each exact hostname is a separate domain resource with its own records.

• Set the returned 300-second TTL when your provider allows it, or the closest supported value. Caches can retain older answers until their existing TTL expires.
• Keep the validation CNAME DNS-only. A proxy or flattening feature that replaces the CNAME answer can prevent AutoCertify from seeing the required target.
• Paste the complete TXT value, including autocertify-domain-verification= and the token. Avoid extra spaces or manually adding quotes unless your DNS provider requires them.

Check DNS, then verify

Query both records. The CNAME answer should match the returned delegation target; the TXT answer should match the entire returned ownership value. DNS tools may display a final dot on hostnames or quotes around TXT answers.

# Set AUTOCERTIFY_HOST to the hostname you registered.
dig +short CNAME "_acme-challenge.$AUTOCERTIFY_HOST"
dig +short TXT "_autocertify-verify.$AUTOCERTIFY_HOST"

# Windows / systems without dig:
nslookup -type=CNAME "_acme-challenge.$AUTOCERTIFY_HOST"
nslookup -type=TXT "_autocertify-verify.$AUTOCERTIFY_HOST"

When both values are visible, request verification. The automation key needs domains:write and certificates:write because verification can start issuance.

curl --fail-with-body \
  -X POST https://api.autocertify.net/v1/domains/$AUTOCERTIFY_DOMAIN_ID/verify-delegation \
  -H "Authorization: Bearer $AUTOCERTIFY_TOKEN"

status: pending means the records have not both matched. Read the response message to see which one is missing. status: verified confirms DNS; the optional certificate summary reports the separate issuance result. Use the certificate refresh endpoint to update provider status afterward.

Share the DNS task

Create a verification link for the domain and give it to the DNS administrator. The public view shows both required records and permits a verification check without signing in. Anyone who holds that link can view the records and trigger verification for its domain, so share it only with the intended administrator.

Traffic routing is a separate step

The CNAME at _acme-challenge handles certificate validation. It does not change the DNS answer for your website hostname. Serving the managed certificate requires website traffic to reach the AutoCertify Cloudflare for SaaS service and the service’s origin configuration to reach the intended website. Confirm these settings with AutoCertify before changing your website’s A, AAAA or CNAME records.

An active provider certificate does not establish that your existing host is serving it. Check the hostname over HTTPS after routing is configured. The managed private key and certificate are held at Cloudflare’s edge and cannot be downloaded as a PEM bundle from AutoCertify.

Troubleshooting

A record is missing or has the wrong value

Check that you edited authoritative DNS, entered the correct record type and avoided appending the zone twice. Compare the public answers with the current response from AutoCertify. A stale ownership token from another workspace will not verify your current domain.

DNS is still propagating

Resolvers can return different cached answers during a change. Confirm the authoritative values, allow existing TTLs to expire, then run verification again. Repeating the check is safe, but verified is a DNS result; inspect the certificate result as well.

An existing validation record conflicts

A CNAME cannot coexist with other ordinary record data at the same name. Before replacing an existing validation record, identify the certificate service that uses it and coordinate the change so you do not interrupt its renewals. AutoCertify must be able to resolve the exact CNAME it returned.

DNS is verified but issuance is pending or failed

Inspect message, the domain’s cert.lastError and its provider status. Cloudflare hostname validation, certificate validation and traffic routing can each require attention. The refresh endpoint checks provider status; it does not force a renewal or alter your routing.

Wildcards

Register the exact hostnames you need. The Cloudflare onboarding integration rejects wildcard: true with 400 wildcard_not_supported_in_minimal_cloudflare_mode. Registering the apex does not also register www or other subdomains.