Partner developer docs

DNS and record management safety

Record writes are powerful. This is the safety contract before partner dashboards or AI agents can mutate DNS.

Principle

DNS mutation is a separate product capability from registration. Registration API keys should not automatically change DNS records or nameservers.

Separate scopesUse `dns:read`, `dns:write`, `nameserver:read`, and `nameserver:write` separately from registration scopes.

Module approvalThe partner should have Basic DNS management or Agent-friendly features enabled before DNS writes are allowed.

Audit firstEvery proposed and applied change should have a durable audit record with request, normalized record, backend response, and status.

Planned endpoints

GET /api/v1/registrations/{domain}/records
POST /api/v1/registrations/{domain}/records
PATCH /api/v1/registrations/{domain}/records/{record_id}
DELETE /api/v1/registrations/{domain}/records/{record_id}
GET /api/v1/registrations/{domain}/nameservers
PUT /api/v1/registrations/{domain}/nameservers

Safety gates

Partner ownershipThe authenticated partner must own the registration being changed.

Active stateThe partner, namespace, and registration must not be paused or inactive.

Backend supportThe active backend adapter must support the requested record operation.

Dry-run firstWrite endpoints should support validation-only dry runs before applying a backend change.

Strict validationRecord names must stay under the registered domain; TTLs, IPs, CNAME conflicts, MX priority, DS format, and bulk limits must be checked.

Rollout order

1. Read-only inventoryKeep registration inventory stable and scoped with `registration:read`.

2. Audit tableAdd a DNS change audit model before any production write endpoint.

3. Record readsAdd adapter read support and `GET records`.

4. Dry-run writesValidate record writes without applying them.

5. Narrow write launchStart with TXT, then add A/AAAA/CNAME/MX, and defer NS/DS until delegation review.