API & MCP

Authentication

An admin creates a token on the API tokens page of the panel. Send it as a bearer token on every request:

curl https://api.dnsaman.com/api/v1/token \
  -H "Authorization: Bearer dnsa_…"

Each token has an owner and a set of permissions:

Security model

• Tokens act as their owner. They reach the same zones that user can. Admin-owned tokens reach every zone. For a service, use a dedicated non-admin user so it can only touch the zones it created or was granted.
• Checked on every request. Revoking a token, disabling its owner or removing a zone grant takes effect on the next call.
• Shown once, stored hashed. The panel keeps only a SHA-256 of the token. If you lose it, revoke it and create a new one.
• Optional IP allowlist and expiry. Pin a service token to its server's addresses (single IPs or CIDR, IPv4 or IPv6), so a leaked token is useless anywhere else.
• Brute-force lockout. Failed authentications share the sign-in form's per-IP lockout.
• No tenant probing. A zone the token may not see returns 404, the same as one that does not exist.
• Audited. Every change is written to the audit log as user (token name) with the caller's IP. Record contents are left out of the log.
• Same validation as the panel. Owner names, record contents and TTLs go through the same checks, so the API cannot write anything the UI would refuse. Apex NS records are managed by the panel.

REST API

Base URL https://api.dnsaman.com/api/v1. Requests and responses are JSON. Successful responses look like {"success": true, "result": …}, and failures like {"success": false, "errors": [{"message": "…"}]}.

# Create a record
curl -X POST https://api.dnsaman.com/api/v1/zones/example.com/records \
  -H "Authorization: Bearer $DNSAMAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "mail", "type": "A", "content": "203.0.113.25", "ttl": 3600}'

# → 201
{"success": true, "result": {"id": 42, "name": "mail", "type": "A", "ttl": 3600,
                             "content": "203.0.113.25", "proxied": false}}

# Change just the TTL
curl -X PATCH https://api.dnsaman.com/api/v1/zones/example.com/records/42 \
  -H "Authorization: Bearer $DNSAMAN_TOKEN" \
  -H "Content-Type: application/json" -d '{"ttl": 300}'

Every change is published to all nameservers before the response returns. Creating a record that already exists with the same name, type and content returns 400, so a retried request does not create a second copy.

Record format

MCP

The MCP endpoint at https://api.dnsaman.com/api/mcp uses Streamable HTTP and is stateless: send JSON-RPC over POST with the same bearer token. Agents only see the tools their token has permission for.

Claude Code

claude mcp add --transport http dnsaman https://api.dnsaman.com/api/mcp \
  --header "Authorization: Bearer dnsa_…"

Any client with a JSON config (Claude Desktop via mcp-remote, Cursor, …)

{
  "mcpServers": {
    "dnsaman": {
      "type": "http",
      "url": "https://api.dnsaman.com/api/mcp",
      "headers": { "Authorization": "Bearer dnsa_…" }
    }
  }
}

Tool arguments are the same fields as the REST bodies, plus zone (and id for record operations).

Example: onboarding a mail domain

The usual flow for a service like a mail provider adding a customer domain. It uses a token with dns.read dns.write zone.create owned by a dedicated user:

T="Authorization: Bearer $DNSAMAN_TOKEN"; J="Content-Type: application/json"
API=https://api.dnsaman.com/api/v1

# 1. Create the zone. result.nameservers is what the customer sets at their registrar.
curl -X POST $API/zones -H "$T" -H "$J" -d '{"name": "customer.com"}'

# 2. Add the mail records.
curl -X POST $API/zones/customer.com/records -H "$T" -H "$J" \
  -d '{"name": "@", "type": "MX", "content": "10 mx1.mail.example.net"}'
curl -X POST $API/zones/customer.com/records -H "$T" -H "$J" \
  -d '{"name": "@", "type": "TXT", "content": "v=spf1 include:_spf.mail.example.net -all"}'
curl -X POST $API/zones/customer.com/records -H "$T" -H "$J" \
  -d '{"name": "rm1._domainkey", "type": "TXT", "content": "v=DKIM1; k=rsa; p=MIIB…"}'
curl -X POST $API/zones/customer.com/records -H "$T" -H "$J" \
  -d '{"name": "_dmarc", "type": "TXT", "content": "v=DMARC1; p=quarantine"}'

# 3. Poll until the registrar change is live (results are cached for 30 s).
curl $API/zones/customer.com/delegation -H "$T"
# → result.delegated && result.ok once the internet sees our nameservers

Errors

Over MCP, a failed tool call comes back as a normal result with isError: true and the same message, so the agent can read it and correct its request.