Authentication

The Dominder API uses API keys. Every request must present your key in an HTTP header. Keys are scoped to a single account and inherit its subscription status.

Your API key

Your key is shown on youraccount page. It looks like:

dmk_5042fef9d749dc61879b94916b7fcfcaf8c493a49278d66ba49c6493acf77c1e

• Thedmk_prefix lets you recognise Dominder keys in logs and secret scanners.
• The rest is 32 bytes of randomness, hex-encoded.
• Each account has exactly one key at a time. Rotating invalidates the previous key immediately.

Sending your key

We accept two header formats - pick whichever fits your stack:

Authorization: Bearer (recommended)

curl https://dominder.co/api/v1/domains \
  -H "Authorization: Bearer dmk_..."

X-API-Key

curl https://dominder.co/api/v1/domains \
  -H "X-API-Key: dmk_..."

Rotating keys

Visit/accountand clickRotate key. The old key stops working the instant the new one is generated; there is no grace period. Plan your rotation accordingly:

1. Generate a new key and save it in your secret manager.
2. Deploy your services with the new key.
3. Hit "Rotate key" in Dominder to invalidate the previous one.

Subscription gating

The API is only available while your account has an active subscription. If your subscription is canceled, unpaid, or past due, the API returns:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error":   "Subscription required",
  "message": "Your account does not have an active subscription. Please subscribe to use the API."
}

Resolve it from thebilling page- we never block an in-flight request, but the next request won't succeed until the subscription is active again.

Examples in other languages

Node.js (native fetch)

const res = await fetch('https://dominder.co/api/v1/domains', {
  headers: { Authorization: `Bearer ${process.env.DOMINDER_API_KEY}` }
});
if (!res.ok) throw new Error(`Dominder API ${res.status}`);
const { domains } = await res.json();

Python (requests)

import os, requests

r = requests.get(
  "https://dominder.co/api/v1/domains",
  headers={"Authorization": f"Bearer {os.environ['DOMINDER_API_KEY']}"},
  timeout=10,
)
r.raise_for_status()
domains = r.json()["domains"]

Ruby (net/http)

require "net/http"
require "json"

uri = URI("https://dominder.co/api/v1/domains")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer " + ENV["DOMINDER_API_KEY"]
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
domains = JSON.parse(res.body)["domains"]