Lucent Drift DDNS token API

This page is intentionally public so people, scripts, routers, browsers, and automation clients can use a Lucent Drift user update token. The token scopes every request to the hostnames owned by that user; no browser session cookie is required for the API calls below.

Quick Start

Replace the placeholder token and hostname. Tokens can be copied or regenerated from the signed-in dashboard.

export LD_BASE="https://lucentdrift.online"
export LD_TOKEN="USER_UPDATE_TOKEN"
export LD_HOST="client-demo.lucentdrift.online"

curl -fsS \
  -H "Authorization: Bearer $LD_TOKEN" \
  "$LD_BASE/v1/hostnames"

Authentication

Use the user update token, not the operator-wide DDNS_API_TOKEN. The preferred form is an HTTP authorization header:

Authorization: Bearer USER_UPDATE_TOKEN

Clients that cannot send an Authorization header may use X-Lucent-Token, X-DDNS-Token, or X-API-Key. Router-style update URLs may still put the token in the query string.

Endpoint Map

Method	Path	Purpose	Body
GET	/v1/hostnames	List subdomains owned by the token.	None
POST	/v1/hostnames	Create a new owned subdomain under an allowed zone.	JSON object
GET	/v1/hostnames/{hostname}	Read one owned subdomain by id, label, or fqdn.	None
PATCH	/v1/hostnames/{hostname}	Update A, AAAA, TXT, TTL, or note fields.	JSON object
DELETE	/v1/hostnames/{hostname}	Delete the owned subdomain and remove its DNS records.	None
GET/POST	/update	DDNS-compatible record update endpoint for routers, scripts, and pollers.	Query string or JSON

List Subdomains

Listing returns only hostnames owned by the token. It also returns the allowed zones so a client knows which suffixes it may use.

curl -fsS \
  -H "Authorization: Bearer $LD_TOKEN" \
  "$LD_BASE/v1/hostnames"

{
  "hostnames": [
    {
      "id": "host_...",
      "fqdn": "client-demo.lucentdrift.online",
      "ipv4": "203.0.113.10",
      "ipv6": null,
      "txt": null,
      "ttl": 60,
      "note": "created by an API client"
    }
  ],
  "allowedZones": ["lucentdrift.online"],
  "defaultZone": "lucentdrift.online",
  "maxHostnames": 10
}

Add A Subdomain

Send a label such as client-demo plus a zone, or send a full hostname. Apex records and reserved names are rejected. Initial A, AAAA, TXT, TTL, and note values are optional.

curl -fsS \
  -H "Authorization: Bearer $LD_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"hostname":"client-demo","zoneDomain":"lucentdrift.online","ipv4":"203.0.113.10","ttl":60,"note":"created by an API client"}' \
  "$LD_BASE/v1/hostnames"

curl -fsS \
  -H "Authorization: Bearer $LD_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{"fqdn":"client-demo.lucentdrift.online","txt":"challenge-value"}' \
  "$LD_BASE/v1/hostnames"

Update A, AAAA, TXT, TTL, And Notes

For general JSON automation, use PATCH /v1/hostnames/{hostname}. For classic DDNS clients, use /update.

curl -fsS \
  -H "Authorization: Bearer $LD_TOKEN" \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{"ipv4":"198.51.100.44","ipv6":"2001:db8::44","txt":"new-value","ttl":120,"note":"rotated by API client"}' \
  "$LD_BASE/v1/hostnames/client-demo.lucentdrift.online"

curl -fsS "$LD_BASE/update?domains=$LD_HOST&token=$LD_TOKEN&ip=198.51.100.44&verbose=true"

curl -fsS \
  -H "Authorization: Bearer $LD_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  -d "{\"domains\":[\"$LD_HOST\"],\"ip\":\"198.51.100.44\",\"txt\":\"new-value\",\"ttl\":120,\"note\":\"updated by API client\"}" \
  "$LD_BASE/update"

Clear DNS Values Without Deleting The Subdomain

Set a field to null or an empty string to remove that DNS value while keeping the hostname reserved to the token owner.

curl -fsS \
  -H "Authorization: Bearer $LD_TOKEN" \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{"ipv4":null,"ipv6":null,"txt":null}' \
  "$LD_BASE/v1/hostnames/client-demo.lucentdrift.online"

curl -fsS "$LD_BASE/update?domains=$LD_HOST&token=$LD_TOKEN&clear=true&verbose=true"
curl -fsS "$LD_BASE/update?domains=$LD_HOST&token=$LD_TOKEN&txt=&clear=true&verbose=true"

Remove A Subdomain

Deleting removes the hostname row and deletes matching A, AAAA, and TXT records from DNS. Use clear operations when the subdomain should remain owned but empty.

curl -fsS \
  -H "Authorization: Bearer $LD_TOKEN" \
  -X DELETE \
  "$LD_BASE/v1/hostnames/client-demo.lucentdrift.online"

Errors And Safety Rules

401 unauthorized: token is missing or invalid.
403 forbidden: account is disabled or banned.
404 hostname_not_found: the token does not own that subdomain.
409 hostname_not_available: the subdomain already exists or the account reached its hostname limit.
429 rate_limited: wait for the retry window before trying again.
Do not print real tokens in chat logs, command output, screenshots, or committed files.
Use the user update token for hostname CRUD and DDNS updates. The global operator token is only for operator-managed records and ACME challenge hooks.