DNS API - User Guide

Overview

The DNS API provides access to your DNS zones through simple HTTP requests. Three authentication methods are available:

• API Key (Recommended for integrations)
• Session Cookie (For web applications)
• IP Whitelist (For trusted servers)

Base URL: https://tools.tornevall.net/api/dns

Getting Started

1. Get an API Key

1. Log in to https://tools.tornevall.net
2. Go to Services → API Keys (Admin access required)
3. Create a new API key
4. Copy the secret key - you won't see it again!

Key Types:

• Global Key - Full access to all zones (admin only)
• Zone Key - Access to specific zone(s)

2. Choose Your Authentication Method

Pick one of these based on your use case:

Option A: API Key Header

curl -H "Authorization: Bearer YOUR_SECRET_KEY" \
  https://tools.tornevall.net/api/dns/zones

Option B: Query Parameter

curl "https://tools.tornevall.net/api/dns/zones?api_key=YOUR_SECRET_KEY"

Option C: IP Whitelist

Ask an admin to whitelist your IP address at /admin/security/api-ip-whitelist. Then use the API without authentication.

API Endpoints

List Your Zones

GET /api/dns/zones

Lists all zones you have access to.

Request:

curl -H "Authorization: Bearer YOUR_KEY" \
  https://tools.tornevall.net/api/dns/zones

Response (200 OK):

{
  "ok": true,
  "count": 3,
  "zones": [
    {
      "zone": "gv32.se",
      "type": "master",
      "records": 42
    },
    {
      "zone": "tornevall.net",
      "type": "master",
      "records": 18
    },
    {
      "zone": "10.10.10.in-addr.arpa",
      "type": "reverse",
      "records": 256
    }
  ]
}

Error Responses:

• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - You don't have access to this zone

Get Zone Records

GET /api/dns/zones/{zoneName}

Retrieve all DNS records for a specific zone.

Request:

curl -H "Authorization: Bearer YOUR_KEY" \
  https://tools.tornevall.net/api/dns/zones/gv32.se

Response (200 OK):

{
  "ok": true,
  "zone": "gv32.se",
  "records": [
    {
      "name": "@",
      "type": "A",
      "ttl": 300,
      "value": "192.0.2.1"
    },
    {
      "name": "www",
      "type": "CNAME",
      "ttl": 300,
      "value": "gv32.se."
    },
    {
      "name": "mail",
      "type": "A",
      "ttl": 300,
      "value": "192.0.2.10"
    },
    {
      "name": "@",
      "type": "MX",
      "ttl": 300,
      "value": "10 mail.gv32.se."
    }
  ]
}

Common Use Cases

Example 1: Read Zone Data in Python

import requests

API_KEY = "your_secret_key_here"
headers = {"Authorization": f"Bearer {API_KEY}"}

# List zones
response = requests.get(
    "https://tools.tornevall.net/api/dns/zones",
    headers=headers
)
zones = response.json()["zones"]

# Get records for first zone
zone_name = zones[0]["zone"]
response = requests.get(
    f"https://tools.tornevall.net/api/dns/zones/{zone_name}",
    headers=headers
)
records = response.json()["records"]

for record in records:
    print(f"{record['name']:20} {record['type']:10} {record['value']}")

Example 2: Read Zone Data in JavaScript

const API_KEY = "your_secret_key_here";

async function getZones() {
    const response = await fetch(
        "https://tools.tornevall.net/api/dns/zones",
        {
            headers: { "Authorization": `Bearer ${API_KEY}` }
        }
    );
    return response.json();
}

async function getRecords(zoneName) {
    const response = await fetch(
        `https://tools.tornevall.net/api/dns/zones/${zoneName}`,
        {
            headers: { "Authorization": `Bearer ${API_KEY}` }
        }
    );
    return response.json();
}

// Usage
const zones = await getZones();
console.log(zones);

const records = await getRecords("gv32.se");
console.log(records);

Error Handling

All errors return JSON with an ok: false status:

{
  "ok": false,
  "error": {
    "code": 401,
    "message": "Invalid API key"
  }
}

Common Error Codes:

• 400 Bad Request - Invalid zone name or parameters
• 401 Unauthorized - Missing or invalid API key
• 403 Forbidden - You don't have access to this zone
• 404 Not Found - Zone doesn't exist
• 500 Internal Server Error - Server error (contact support)

Rate Limiting

No rate limits are currently enforced. Reasonable usage is expected.

Security Best Practices

🔒 Always use HTTPS - Never transmit API keys over HTTP 🔑 Keep API keys secret - Treat them like passwords 🛑 Use IP whitelist for servers - Restrict access to known IP addresses 🔄 Rotate keys regularly - Request a new key from admins if compromised 👤 Use zone-specific keys - Don't use global keys unless necessary

Access Control

Zone access is controlled through roles:

• Viewer - Read-only access to records
• Editor - Read and modify records
• Owner - Full control + delegation to others

Contact an admin to grant you access to additional zones.

Last Updated: 2026-02-13