Quickstart

This walkthrough uses Bash, curl and jq. You need an AutoCertify workspace, permission to edit the hostname’s authoritative DNS, and a website routing setup supported by the AutoCertify service. Confirm the traffic destination and origin configuration before changing website DNS. Cloudflare hosts the managed certificate at its edge.

The JSON examples illustrate response shapes. Their IDs, times and redacted DNS values are documentation data. The commands save and reuse your API responses; publish the records returned for your own hostname.

1. Get an API key

Sign in to the dashboard as an owner or admin and open Settings → API keys. Create a key with domains:read, domains:write, certificates:read and certificates:write for this workflow. Keys begin with ac_live_; the complete secret is shown at creation or rotation only. Store it in your secret manager.

Run the following in Bash. The key prompt hides your input and avoids putting the secret in a command saved to shell history. Enter the hostname you control, such as your shop’s subdomain.

set -euo pipefail
read -r -s -p "AutoCertify API key: " AUTOCERTIFY_TOKEN
printf '\n'
read -r -p "Hostname to secure: " AUTOCERTIFY_HOST
export AUTOCERTIFY_TOKEN AUTOCERTIFY_HOST

2. Create a domain

Register the hostname and save the returned Domain. Its validation.delegation contains the CNAME record, and validation.ownership contains your workspace’s TXT proof of ownership.

curl --fail-with-body --silent --show-error \
  -X POST https://api.autocertify.net/v1/domains \
  -H "Authorization: Bearer $AUTOCERTIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg apex "$AUTOCERTIFY_HOST" '{apex: $apex}')" \
  --output autocertify-domain.json

jq . autocertify-domain.json
AUTOCERTIFY_DOMAIN_ID="$(jq -er '.id' autocertify-domain.json)"
export AUTOCERTIFY_DOMAIN_ID

{
  "id": "8a7260d9-4f3f-4cea-bc6f-60a1b87ddf10",
  "apex": "shop.example.com",
  "orgId": "47a33825-ea1f-469e-a984-7237de8e83ac",
  "createdAt": "2026-02-04T18:22:10.000Z",
  "updatedAt": "2026-02-04T18:22:10.000Z",
  "tags": [],
  "validation": {
    "status": "pending",
    "delegation": {
      "type": "CNAME",
      "host": "_acme-challenge.shop.example.com",
      "value": "<DCV target returned for your domain>",
      "ttl": 300
    },
    "ownership": {
      "type": "TXT",
      "host": "_autocertify-verify.shop.example.com",
      "value": "autocertify-domain-verification=<your ownership token>",
      "ttl": 300
    }
  },
  "cert": { "status": "none" },
  "opsStatus": "action_needed"
}

The equivalent create request using Node.js with built-in fetch:

const token = process.env.AUTOCERTIFY_TOKEN;
const apex = process.env.AUTOCERTIFY_HOST;
if (!token || !apex) {
  throw new Error("Set AUTOCERTIFY_TOKEN and AUTOCERTIFY_HOST first.");
}

const response = await fetch("https://api.autocertify.net/v1/domains", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + token,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ apex }),
});
const domain = await response.json();
if (!response.ok) {
  throw new Error(response.status + " " + domain.code + ": " + domain.message);
}
console.log({
  domainId: domain.id,
  delegation: domain.validation.delegation,
  ownership: domain.validation.ownership,
});

3. Add both DNS records

Print the two records from your saved response. Each output row contains type, host, value and TTL. Add both at the provider that manages authoritative DNS for your domain.

# Print the records from your create-domain response.
jq -r '.validation | [.delegation, .ownership][] |
  [.type, .host, .value, (.ttl | tostring)] | @tsv' \
  autocertify-domain.json

The CNAME delegates certificate validation. The TXT record binds the hostname to your workspace. Use the returned values exactly, keep the CNAME DNS-only if your provider offers proxying, and use the returned 300-second TTL where supported. Keep both records published while AutoCertify manages the hostname.

For host-field examples, propagation checks and verification links you can share with your DNS administrator, see the delegated DCV guide.

4. Verify the records

Once both records are visible, ask AutoCertify to verify them. A successful check starts or checks issuance when the domain does not already have an active certificate.

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

jq . autocertify-verification.json

{
  "status": "verified",
  "checkedAt": "2026-02-04T18:41:52.000Z",
  "message": "DNS records verified successfully. Certificate issuance is now being checked. Cloudflare issuance is pending: hostname=pending, ssl=pending_validation.",
  "certificate": {
    "certificateId": "49c1a8d4-146e-48fc-ac52-4952e1c10876",
    "status": "pending",
    "message": "Cloudflare issuance is pending: hostname=pending, ssl=pending_validation."
  }
}

status: pending means one or both DNS records could not be confirmed. Read message, correct any mismatches, allow time for propagation, and repeat the check. status: verified describes DNS verification; check the separate certificate status before treating issuance as complete. If issuance fails, the message explains the failure and certificate can be absent.

5. Refresh certificate status

After DNS verification succeeds and a certificate exists, call refresh to fetch the provider’s current status. The command reuses the certificate ID from verification or finds the most recent certificate for an already-active domain. If the certificate list is empty, return to the verification message and resolve the issuance error first.

AUTOCERTIFY_CERTIFICATE_ID="$(jq -r \
  '.certificate.certificateId // empty' autocertify-verification.json)"

# An already-active domain may have no certificate summary in verification.
if [ -z "$AUTOCERTIFY_CERTIFICATE_ID" ]; then
  curl --fail-with-body --silent --show-error \
    -X POST https://api.autocertify.net/v1/domains/$AUTOCERTIFY_DOMAIN_ID/certificates/query \
    -H "Authorization: Bearer $AUTOCERTIFY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{}' --output autocertify-certificates.json
  AUTOCERTIFY_CERTIFICATE_ID="$(jq -er '.items[0].id' autocertify-certificates.json)"
fi
export AUTOCERTIFY_CERTIFICATE_ID

curl --fail-with-body --silent --show-error \
  -X POST https://api.autocertify.net/v1/certificates/$AUTOCERTIFY_CERTIFICATE_ID/refresh \
  -H "Authorization: Bearer $AUTOCERTIFY_TOKEN"

{
  "certificateId": "49c1a8d4-146e-48fc-ac52-4952e1c10876",
  "status": "active",
  "nextRenewalAt": "2026-04-05T18:43:07.000Z",
  "message": "Cloudflare reports the custom hostname and SSL certificate are active."
}

Repeat the refresh at a reasonable interval, such as 30 seconds, while status remains pending. Stop and inspect the provider message if it becomes error. active requires both the Cloudflare custom hostname and SSL status to be active. Read the full saved certificate for notAfter, provider status and identifiers:

curl --fail-with-body \
  https://api.autocertify.net/v1/certificates/$AUTOCERTIFY_CERTIFICATE_ID \
  -H "Authorization: Bearer $AUTOCERTIFY_TOKEN"

The GET request reads the saved record; refresh updates it from Cloudflare. When an expiry is available, the refresh summary and Domain.cert.nextRenewalAt contain a planning timestamp 30 days before expiry. Cloudflare controls managed renewal timing; this field is not a scheduled AutoCertify renewal job.

6. Confirm website HTTPS and keep monitoring

With the service’s traffic routing and origin configuration in place, open the website over HTTPS and run the HTTPS scan. Confirm status: secure and details.certificateValid: true for the connection visitors will use.

curl --fail-with-body \
  -X POST https://api.autocertify.net/v1/site-scan/https \
  -H "Authorization: Bearer $AUTOCERTIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg host "$AUTOCERTIFY_HOST" '{urlOrDomain: $host}')"

DNS validation alone does not route visitors through Cloudflare or install a certificate on another host’s origin server. If the scan fails, review the destination, origin and reported certificate error. Keep the validation records in place and continue status checks to detect problems before expiry.

Add webhooks for supported issuance notifications. The API reference describes the request bodies, scopes, errors and response fields used in this workflow.