CAA Record API: Check Certificate Authority Authorization Records in JSON

Introduction

A CAA record lookup API gives security teams a structured way to check Certificate Authority Authorization records without relying on manual DNS commands. Instead of running dig one domain at a time, you can audit CAA DNS records as JSON across production domains, vendors, acquisition targets, and customer-facing subdomains.

With the WhoisJSON DNS Lookup API, CAA records are returned by the documented /nslookup endpoint alongside A, MX, TXT, NS, DMARC, MTA-STS, and TLSRPT records. The API response includes CAA records with flags, tag, and value fields when they exist. Combine that DNS policy with SSL certificate monitoring for a complete view: policy before issuance, certificate state after issuance.

What Is a CAA Record?

CAA stands for Certification Authority Authorization. It is a DNS record type defined for certificate issuance control. Instead of trusting every public certificate authority equally, the domain owner can publish a policy that says which CAs may issue certificates for the domain.

example.com. 3600 IN CAA 0 issue "letsencrypt.org"
example.com. 3600 IN CAA 0 issuewild ";"
example.com. 3600 IN CAA 0 iodef "mailto:[email protected]"

The exact record values depend on your certificate authority and internal policy. The important part is the structure: each CAA record has a flag, a tag, and a value.

The formal standard is RFC 8659. For an API integration, you normally do not need to implement the DNS parsing yourself. You need to query the record, normalize it into structured data, and compare it with the policy your organization expects.

Why CAA Matters for Certificate Security

CAA is not a magic protection layer, and it does not replace certificate transparency monitoring, registrar security, DNS account security, or incident response. It is still useful because it makes certificate authority policy explicit and machine-checkable.

CAA is especially relevant when it is combined with other public signals: WHOIS ownership and expiry from the WHOIS API, DNS records from DNS lookup, and current certificate details from SSL certificate checks.

CAA Audit vs SSL Certificate Monitoring

CAA auditing and SSL certificate monitoring answer different questions. Treating them as the same control creates blind spots.

A mature workflow uses both. Query CAA through /nslookup to understand the policy, then query /ssl-cert-check to verify what is actually deployed. If the certificate issuer does not match your expected CAA policy, that domain deserves review even when the certificate is technically valid.

CAA Record Lookup API: Query CAA Records in JSON

The WhoisJSON OpenAPI definition documents /nslookup as a DNS endpoint that returns active records in one response. Covered record types include A, AAAA, CNAME, MX, NS, TXT, SOA, CAA, DMARC, BIMI, MTASTS, and TLSRPT.

curl "https://whoisjson.com/api/v1/nslookup?domain=example.com" \
  -H "Authorization: TOKEN=YOUR_API_KEY"

When CAA records exist, the CAA key contains an array of objects with flags, tag, and value fields.

{
  "CAA": [
    {
      "flags": 0,
      "tag": "issue",
      "value": "letsencrypt.org"
    },
    {
      "flags": 0,
      "tag": "iodef",
      "value": "mailto:[email protected]"
    }
  ]
}

Authentication uses the Authorization: TOKEN=YOUR_API_KEY header. Each response also includes the Remaining-Requests quota header, which matters when you audit many domains in a portfolio.

How to Interpret CAA Records

The right result depends on the domain's role. A parked campaign domain, a production login domain, and a vendor's mail gateway should not be judged with the same severity. Start by classifying domain criticality, then evaluate the CAA records against expected policy.

A missing CAA record is not proof of compromise. It is a governance gap. The purpose of an API-based audit is to separate "unknown" from "intentional" and give teams a list they can fix.

Python Example: Audit One Domain

This example checks the documented CAA response shape and keeps the parsing defensive. It does not assume that the CAA key exists for every domain.

import os
import requests

API_KEY = os.environ["WHOISJSON_API_KEY"]
BASE_URL = "https://whoisjson.com/api/v1"
APPROVED_CAS = {"letsencrypt.org", "digicert.com"}

def get_dns(domain):
    response = requests.get(
        f"{BASE_URL}/nslookup",
        params={"domain": domain},
        headers={"Authorization": f"TOKEN={API_KEY}"},
        timeout=15,
    )
    response.raise_for_status()
    return response.json()

def audit_caa(domain, critical=False):
    dns = get_dns(domain)
    caa_records = dns.get("CAA") or []
    findings = []

    if not caa_records:
        severity = "MEDIUM" if critical else "LOW"
        findings.append({
            "severity": severity,
            "message": "No CAA records found",
        })
        return findings

    issue_values = {
        record.get("value", "").lower()
        for record in caa_records
        if record.get("tag") == "issue"
    }
    issuewild_values = {
        record.get("value", "").lower()
        for record in caa_records
        if record.get("tag") == "issuewild"
    }
    has_iodef = any(record.get("tag") == "iodef" for record in caa_records)

    unexpected = issue_values - APPROVED_CAS
    if unexpected:
        findings.append({
            "severity": "HIGH",
            "message": f"Unexpected CAA issuer(s): {', '.join(sorted(unexpected))}",
        })

    wildcard_allowed = any(value and value != ";" for value in issuewild_values)
    if wildcard_allowed:
        findings.append({
            "severity": "HIGH",
            "message": "Wildcard certificate issuance is allowed",
        })

    if critical and not has_iodef:
        findings.append({
            "severity": "LOW",
            "message": "No iodef reporting address found",
        })

    return findings

if __name__ == "__main__":
    for finding in audit_caa("example.com", critical=True):
        print(f"{finding['severity']}: {finding['message']}")

A failed audit should produce output that a security or platform team can act on immediately.

HIGH: Unexpected CAA issuer(s): sectigo.com
LOW: No iodef reporting address found

For production, store expected CAs per environment or business unit. Some teams use Let's Encrypt for edge services and DigiCert for corporate domains. The audit should check the policy you actually intend, not a universal list copied from another organization.

Bulk CAA Audit Across Vendors and Domain Portfolios

CAA becomes more valuable when it is checked across a list. One domain is easy to inspect manually. Two hundred vendor, product, country-code, and acquisition domains are not.

• Vendor due diligence: check whether vendors with access to customer data publish clear certificate authority policy on their primary domains.
• Domain portfolio review: find production domains without CAA before they become certificate governance exceptions.
• M&A technical diligence: identify mismatched certificate policy across acquired brands, legacy domains, and regional properties.
• Compliance evidence: produce a repeatable export showing which domains have CAA, which CAs are allowed, and which records need remediation.

If you are processing large domain lists, combine this workflow with the concurrency and retry patterns from the bulk WHOIS lookup guide and the rate limits and retries guide. CAA checks use the DNS endpoint, but the same production rules apply: bounded concurrency, explicit timeouts, and clear handling for 429 or temporary failures.

Where CAA Fits in a Security Workflow

CAA is a narrow signal. It becomes more useful when it is part of a domain security workflow that connects ownership, DNS configuration, certificate state, and monitoring.

This is why CAA links naturally to vendor domain security audits, domain monitoring baselines, and attack surface management. It is not the whole program. It is one high-signal control inside it.

Operational Checks That Matter

A useful CAA audit is more than "does this domain have a CAA record?" The practical details are propagation, subdomain coverage, wildcard policy, and whether the live certificate matches the intended policy.

CRITICAL_HOSTS = ["login", "api", "app", "dashboard", "auth", "checkout"]

def candidate_domains(root_domain):
    yield root_domain
    for host in CRITICAL_HOSTS:
        yield f"{host}.{root_domain}"

def audit_zone_family(root_domain):
    report = {}
    for domain in candidate_domains(root_domain):
        dns = get_dns(domain)  # same /nslookup helper as above
        report[domain] = dns.get("CAA") or []
    return report

This does not replace a full subdomain inventory. It is a lightweight guardrail for the names that usually carry authentication, API traffic, payment flows, or customer sessions. For broader discovery, start from your asset inventory or a subdomain discovery workflow, then run the same CAA check on the resulting list.

FAQ

Conclusion

CAA records are small DNS records with high security value. By checking them through the WhoisJSON DNS Lookup API, teams can turn certificate authority policy into a repeatable control across production domains, vendors, acquisitions, and customer-facing subdomains.

Combined with SSL certificate checks and WHOIS/RDAP data, CAA auditing becomes part of a broader domain security baseline instead of a one-off DNS lookup. Query the CAA DNS record, compare the allowed CAs with your expected certificate issuance policy, verify the live certificate issuer, and monitor the result over time.