The DNSconfig API

Quickstart

Five minutes from nothing to a verified record. Create an account at /app, then mint a key under Account → API keys (see Creating an API key).

export K="Authorization: Bearer dnsv_your_key_here"
export B="https://dns-config.net"

# 1. A customer. (Every account starts with one called "default" —
#    skip this if you don't need the customer tier.)
curl -sX POST $B/api/admin/customers -H "$K" \
  -H 'Content-Type: application/json' \
  -d '{"id":"acme","name":"Acme Corp"}'

# 2. The record they must publish.
curl -sX POST $B/api/admin/customers/acme/records -H "$K" \
  -H 'Content-Type: application/json' \
  -d '{"domain":"acme.com","hostname":"em.acme.com",
       "type":"CNAME","value":"u7.wl.sendgrid.net"}'

# 3. Check it against live DNS.
curl -sX POST $B/api/admin/customers/acme/verify -H "$K"

# 4. A link your customer can open to fix it themselves.
curl -sX POST $B/api/admin/customers/acme/onboarding-link -H "$K"

After that, a scheduled sweep re-verifies on its own and alerts you when a passing record drifts. You do not need to poll.

Authentication

Every request to /api/admin/** carries a per-tenant API key as a bearer token:

curl -s https://dns-config.net/api/admin/customers \
  -H "Authorization: Bearer dnsv_xK3…"

The key resolves to exactly one account, and that identity scopes every operation — so an id belonging to somebody else simply does not resolve and returns 404. We never answer 403 there, because that would confirm the id exists.

Keys are transmitted over HTTPS only, stored as a SHA-256 hash, and never returned by any read endpoint.

Creating an API key

Sign in to the console, open Account → API keys, give the key a name, tick the scopes it needs, and press Mint key. The plaintext key is shown once.

There is also an API for it, but note what it will not accept:

POST /api/admin/api-keys
{ "name": "ci-pipeline", "scopes": ["write"] }

→ 201
{ "id": "3f9c…", "name": "ci-pipeline", "scopes": ["write"],
  "created_at": "2026-09-10T09:12:44Z", "legacy": false,
  "api_key": "dnsv_xK3…" }

Scopes

Each key carries a subset of three scopes. They are split by blast radius rather than by resource, so the usual shapes fall out naturally: a status dashboard gets read, a provisioning job gets write, and neither can touch your stored credentials.

write implies read — a provisioning key that cannot read back what it wrote is broken for every realistic caller. secrets implies nothing and is implied by nothing.

There is no billing scope. Subscriptions are managed in the console, not over the API — so no key you mint can reach your payment details, by construction.

secrets covers reads as well as writes because GET /api/admin/alert-config returns your Slack and webhook URLs in plaintext, and those are bearer credentials in their own right.

A call outside a key's scopes returns 403 naming the scope it lacks:

{ "detail": "api key lacks the 'write' scope" }

Rotating a key without downtime

Keys are additive — up to 20 per account — so rotation has no gap in service:

1. Mint the replacement.
2. Deploy it.
3. Revoke the old one (Revoke in the console, or DELETE /api/admin/api-keys/{id}).

Revocation takes effect immediately.

If your account was set up for you, you may also have a key marked legacy in the list. It predates scopes and carries all of them — narrowing it silently would break whatever is already using it. Revoke it once your scoped keys are deployed.

Data model

Your account
 └── Customer "acme"                    one per end-customer
      ├── Record  em.acme.com CNAME u7.wl.sendgrid.net
      ├── Record  acme.com     TXT   "v=spf1 include:…"
      └── TLS endpoint  acme.com:443    Pro and up

Records are expected state — what you declare a customer ought to publish. Verification resolves each one against live DNS and reports the difference.

Every account is created with one implicit customer called default. If you don't need the customer tier, address /api/admin/customers/default/records and ignore it.

Customers & records

A customer is a container with an id you choose and a display name. A record is one expected DNS entry beneath it: a hostname of a given type that must resolve to a given value, within a domain.

Deleting a customer deletes its records and run history. Field-by-field shapes for both are in Objects.

Verification

POST /api/admin/customers/{id}/verify resolves every record and returns them grouped by domain. Each record echoes its configured fields and adds:

Why a quorum

Each record is queried in parallel across several independent public resolvers, and counts as ok only when a strict majority of those that answered agree. Resolvers that error are dropped from the vote rather than poisoning it.

This is why a record you just changed reports PROPAGATING instead of failing: one stale cache cannot produce a false alarm, and a partial resolver outage degrades gracefully instead of paging you.

Failure reasons

Run history is kept per customer at GET /api/admin/customers/{id}/runs.

Customer links

Rather than relaying DNS instructions yourself, mint a signed link and send it to the customer:

POST /api/admin/customers/acme/onboarding-link

→ { "url": "https://dns-config.net/acme?t=eyJ…",
    "expires_at": "2026-10-10T09:12:44Z" }

They open it with no account and no password, see exactly their own records with copy buttons, press Re-check, and — where their DNS provider supports Domain Connect — get a one-click apply button.

Vendor auto-pull

Instead of declaring records by hand, connect the vendor account that generates them and let each sweep re-pull:

The connection object

A connection is source plus two free-form maps: credentials (the vendor secret — write-only) and config (everything else). Which keys go in each depends on the vendor; see the table below.

POST /api/admin/vendor-connections
{
  "source": "sendgrid",
  "credentials": { "api_key": "SG.xxxx" },
  "config":      { "only_valid": false },
  "enabled": true
}

→ 201
{ "id": "9c2f…", "tenant_id": "acme", "source": "sendgrid",
  "config": { "only_valid": false }, "enabled": true,
  "created_at": "2026-09-10T09:12:44Z",
  "has_credentials": true }

Note what comes back: has_credentials, never the credentials. They are encrypted before storage and no read path can recover them — the same one-way treatment as an API key.

On PATCH, omitting credentials leaves the stored secret untouched; sending {} clears it. So you can flip enabled or edit config without re-sending the key.

Per-vendor fields

Required fields are marked; everything else is optional and has a sensible default. config keys not listed here are ignored.

Setting one up for the first time? Step-by-step guides walk through the API key, adding a domain, and the first pull: SendGrid · Mailgun.

SendGrid subusers are a Pro-and-above feature. On a plan without them the puller falls back to the account's own domain authentications automatically — you do not need to set single_account unless you want to skip the lookup.

Pulling on demand

A scheduled sweep re-pulls every connection hourly, but you rarely want to wait for it after entering a credential:

POST /api/admin/vendor-connections/{id}/sync

→ { "tenant": "acme", "source": "sendgrid",
    "added": 3, "updated": 0, "retired": 0, "unchanged": 0 }

Idempotent — a second call reports everything as unchanged. Records the vendor stops reporting are retired, because the vendor is the source of truth for records it owns. Records you entered by hand are never touched: reconciliation is scoped to the connection's own source tag.

422 means no puller is registered for that source, 409 that the connection is disabled, and 502 that the vendor API could not be reached.

Managing connections, and pulling, needs the secrets scope.

Objects

Every shape the tenant API accepts and returns. Timestamps are ISO 8601 UTC strings. A field marked req is required on create; anything else may be omitted and takes the stated default. PATCH bodies accept any subset of the mutable fields — omitted keys are left unchanged.

Customer

health (also the body of GET /api/health/{cid}):

Record

Verification run

Returned by POST …/verify. GET …/runs returns the same object without records.

record result:

Onboarding link

TLS endpoint

TLS policy

One per tenant, at GET/PUT /api/admin/tls-policy.

TLS run

POST …/tls-verify and GET …/tls return {started_at, status, ok, total, endpoints[]}; GET …/tls-runs omits endpoints. Each endpoint result:

Alert config

One per tenant, at GET/PUT /api/admin/alert-config. Needs the secrets scope — the read returns the webhook URLs in plaintext.

Webhook and SMTP targets must be https (or a reachable relay) and must resolve to a public address — internal and link-local targets are refused at save time and again at send time, so a DNS rebind cannot smuggle one through.

Vendor connection

See Vendor auto-pull for the object and its per-vendor fields.

Sync summary

Returned by POST /api/admin/vendor-connections/{id}/sync.

API key

Usage

GET /api/admin/usage:

limits and usage share these keys:

Errors

Failures carry a detail string:

{ "detail": "api key lacks the 'write' scope" }

A tripped plan limit is the one exception — a flat, machine-readable body:

{ "error": "limit_exceeded", "limit": "max_customers",
  "current": 25, "max": 25 }

Errors & limits

A tripped plan limit returns a flat, machine-readable body:

{ "error": "limit_exceeded", "limit": "max_customers",
  "current": 25, "max": 25 }

Your plan caps customers, records per customer, vendor connections, distinct apex domains, TLS endpoints, and monitoring frequency. GET /api/admin/usage returns your live counts against each cap — the same numbers the enforcement paths check, so it shows exactly what will trip.

The apex-domain cap counts distinct domains, not records: adding more records to a domain you already use never consumes a slot.

Endpoint reference

All paths are relative to https://dns-config.net.

Customers & records

Verification & links

TLS — Pro and up

Alerts & vendors — secrets scope

Account

Public — signed customer links, no key