CNF API · v1

Overview

Version 1 exposes DNS operations for zones you have claimed through DNS Management. Create and revoke tokens under Account → API keys.

Base URL and versioning

https://api.c.nf/v1

All endpoints are below /v1. Breaking changes will use a new major-version path. Backwards-compatible fields and endpoints may be added to v1 and will be recorded in the changelog.

Authentication and scopes

Every request that reads or changes account data must include a Bearer token. Tokens begin with cnf_ followed by 32 hexadecimal characters.

curl https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer cnf_a1b2c3d4e5f60718293a4b5c6d7e8f90"

Tokens are stored as one-way hashes and the complete value is shown only when it is created. If a token is lost, revoke it and create another.

Each token carries scopes. A token with no configured scope receives dns:read by default. Write scope also permits reads.

A mismatch returns 403 forbidden_scope and includes both required_scopes and token_scopes for diagnosis.

Per-user isolation

A Bearer token resolves to exactly one user_id. Every zone handler checks that user’s verified claim before any read or write. There is no administrator override, impersonation path or cross-user bypass.

Even a token with * can act only on zones verified by its own user. Attempting to use another account’s zone returns 403 forbidden_zone.

Response envelope

Successful response

{
  "success": true,
  "data": { "zones": [] },
  "request_id": "req_abc123def456abcd"
}

Error response

{
  "success": false,
  "error": "forbidden_zone",
  "message": "zone not verified for this account (or does not exist)",
  "request_id": "req_abc123def456abcd",
  "zone": "example.com"
}

request_id appears on every response and is safe to record with client-side logs.

Error codes

Zone verification

When POST /v1/dns/zones claims a zone, the server chooses one of these paths:

1. Instant verification (method: "auto") — Used when no other account has claimed the zone. The claim is immediately verified. Records become authoritative only after the owner points the registrar’s NS delegation to the returned nameservers.
2. TXT verification — Used for a contested claim. Add the returned TXT value at _cnfdns-verify.<zone>, then call POST /v1/dns/zones/{zone}/verify.
3. Legacy NS verification — Older pending claims may use verify_method: "ns". Verification compares the zone’s live NS answers with its expected nameserver set.

Verification is idempotent. Repeating it for a verified claim returns verified: true without changing the claim.

Record types and limits

Supported record types

A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR, SPF.

priority is required for MX and SRV and ignored for other types. ttl must be between 60 and 2,592,000 seconds.

Endpoints

Request fields

Create a zone claim

Create a DNS record

Update a DNS record

Examples

curl -H "Authorization: Bearer $CNF_TOKEN" \
  https://api.c.nf/v1/dns/zones

curl -X POST https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com"}'

curl -X POST https://api.c.nf/v1/dns/zones/example.com/verify \
  -H "Authorization: Bearer $CNF_TOKEN"

curl -X POST https://api.c.nf/v1/dns/zones/example.com/records \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"api","value":"192.0.2.10"}'

Quick start

1. Create an API key with dns:write at Account → API keys, and copy it when it is shown.
2. Store the token in a protected environment variable on your machine.
3. Call GET /v1/account/me to confirm the token and its scopes.
4. Claim a zone. The response says whether verification is instant, TXT-based or legacy NS-based.
5. Complete the returned DNS proof when one is required, then call the verify endpoint.
6. Create, read, update or delete records only after the claim is verified.

Changelog

v1.1.0 — zone management

• Added API-based zone claims, including instant and TXT verification paths.
• Added single-zone status and idempotent verification endpoints.
• Added claim revocation without implicit record deletion.
• Added verified, pending and all filters to the zone list.

v1.0.0 — initial release

• Added Bearer-token authentication and per-user zone isolation.
• Added read and write scopes.
• Added account, zone-list and record-management endpoints.
• Added a consistent response envelope with a request identifier.