API documentation

Authentication

Every request requires your personal API key, which you can find in Settings. The safest option is to send it as a bearer token in the Authorization header.

Authorization: Bearer DEIN_API_KEY
X-API-Key: DEIN_API_KEY

Alternatively, the key and api_key URL parameters are supported.

Send a request

Query parameters are read for all methods. POST, PATCH and DELETE also accept a JSON body with Content-Type application/json.

Supported record types: A, AAAA, CNAME, TXT and MX for own domains.

Examples

Set an A record to the detected client IP

curl "https://rb-ddns.net/?api=update&host=zuhause&type=A&key=DEIN_API_KEY"

Update an AAAA record using JSON

curl -X PATCH "https://rb-ddns.net/?api=update" \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"zuhause","record_type":"AAAA","target_value":"2001:db8::24","ttl":300}'

Add another TXT value in a own domain

curl -X POST "https://rb-ddns.net/?api=update" \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"_acme-challenge","domain":"example.com","record_type":"TXT","target_value":"challenge-token","ttl":300,"append":true}'

The response contains the public_id of this individual TXT value. Use that exact ID for deletion so other values in the same TXT RRset remain untouched.

Delete a record from a own domain

curl -X DELETE "https://rb-ddns.net/?api=update" \
  -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public_id":"rec_..."}'

Let’s Encrypt wildcard certificates

Wildcard certificates are issued through the DNS-01 challenge. The authentication hook adds the value supplied by Certbot as another TXT record below _acme-challenge, waits until it is visible on every authoritative nameserver, and returns its unique public_id to Certbot. The cleanup hook then deletes only that value.

This allows example.com and *.example.com to be included in one certificate even when Let’s Encrypt requires two different TXT values at the same name at the same time.

Automatic setup

The following command downloads the RB-ddns installer and runs it with root privileges:

curl -fsSL "https://rb-ddns.net/public/downloads/install-certbot-rbddns.sh" | sudo bash

A fixed zone is not required. The authentication hook sends the complete challenge name to the API. RB-ddns automatically detects the managed domain and returns it for the nameserver check. This allows the same API key to be used for any number of domains in the account.

Installation requires Linux or another Unix system, Bash, and curl. Certbot, Python 3, and dig are also required to request a certificate; the installer reports any missing programs.

Request the certificate

sudo certbot certonly --manual --preferred-challenges dns \
  --manual-auth-hook /usr/local/lib/rb-ddns/auth.sh \
  --manual-cleanup-hook /usr/local/lib/rb-ddns/cleanup.sh \
  -d *.example.com -d example.com

Certbot stores the hook configuration for later renewals. The API key is automatically read from the protected configuration file, while the matching domain is detected for every challenge. Afterwards, test the complete process with sudo certbot renew --dry-run.

Responses and errors

The API always responds with JSON. A successful update contains ok, DNS synchronisation information, and the updated record.

{
  "ok": true,
  "sync": {
    "ok": true,
    "message": "DNS-Record wurde aktualisiert."
  },
  "record": {
    "public_id": "rec_...",
    "hostname": "zuhause",
    "domain": "rb-ddns.net",
    "record_type": "A",
    "target_value": "203.0.113.24",
    "ttl": 300,
    "enabled": true
  }
}