DDNS Update Protocols

Available on: Plus Pro Elite (API key auth) | All plans (username/password auth for routers)

1. What This Feature Does

DDNS Update Protocols provide multiple HTTP endpoints compatible with standard DynDNS update protocols. These endpoints allow routers, scripts, and the CertaDNS desktop client to automatically update DNS records when the public IP address changes. You can authenticate using an API key (Bearer token), HTTP Basic Auth with username and password, or query parameters. All endpoints are functionally equivalent and support both GET and POST requests.

When a client makes an update request, the system validates the authentication, locates the domain, validates the IP address against the record type (A or AAAA), updates the PowerDNS record, and logs the change in the domain update audit trail. The response follows the DynDNS protocol standard, returning status codes like good, nochg, badauth, or nohost.

2. When You Should Use It

• You have a router (Ubiquiti, pfSense, DD-WRT, ASUS, Netgear, TP-Link, or others) that supports DynDNS2 protocol and want it to automatically update your CertaDNS domain when your public IP changes.
• You run a script or service on a server that detects IP changes and needs to push updates to DNS without manual intervention.
• You want to use the CertaDNS desktop client to monitor your IP and update domains automatically.
• You need to update DNS records programmatically from a CI/CD pipeline, monitoring tool, or automation framework.

3. When You Should Not Use It

• Manual dashboard updates are sufficient: If you only need to update IPs occasionally and are comfortable using the dashboard, the DDNS protocols add unnecessary complexity. See Dynamic DNS Domains for manual update instructions.
• Static IP addresses: If your IP never changes, there is no need for automated updates. Use the DNS Record Management feature for static records.
• Non-IP record types: DDNS protocols only update A and AAAA records. For other record types (MX, CNAME, TXT, NS), use the DNS Record Manager on an imported zone.

4. Prerequisites

• A registered CertaDNS account with at least one DDNS domain created. See Dynamic DNS Domains for instructions.
• For API key authentication: an active API key with the domains:update scope. Requires Plus, Pro, or Elite plan. See API Keys for generation instructions.
• For username/password authentication: your CertaDNS account username or email address and your account password. Available on all plans, including Free.
• The client making the update must have internet access to www.certadns.com on port 443 (HTTPS).

5. How It Works (Brief)

When a client (router, script, or desktop app) detects that your public IP has changed, it sends an HTTP request to one of the DDNS update endpoints. The request includes the hostname (FQDN) to update, optionally the new IP address, and authentication credentials. If the IP is omitted, the system extracts the client's public IP from the X-Forwarded-For header or request.client.host.

The server validates authentication in this priority order: Bearer token (API key), HTTP Basic Auth, then query parameters. If authentication succeeds, it locates the domain owned by the authenticated user. It validates the IP format against the record type (IPv4 for A records, IPv6 for AAAA records). If the IP differs from the current value, the record is updated in PowerDNS and a good {IP} response is returned. If the IP matches the current value, a nochg {IP} response is returned. Errors return badauth, nohost, or dnserr according to the DynDNS standard.

Every update creates a DomainUpdate record that logs the old IP, new IP, timestamp, source IP, country code, IP intelligence tags, and user agent. This audit trail is visible in the domain's update history.

6. How to Use It

Available endpoints

All endpoints are functionally equivalent. Choose the one that matches your client's configuration options.

Endpoint	Method	Description
/domains/update	GET, POST	Basic DDNS update. Accepts query params or Basic Auth.
/domains/nic/update	GET, POST	NIC protocol compatible. Accepts Bearer, Basic Auth, or query params.
/domains/v2/update	GET	DynDNS2 alias. Same behavior as /nic/update.
/domains/dyndns/update	GET	Legacy DynDNS alias. Same behavior as /nic/update.

Authentication methods

The /nic/update endpoint (and its aliases) processes authentication in this priority order:

1. Bearer token: Authorization: Bearer ak_your_api_key. The API key must be active (is_active=True). The last_used_at timestamp is updated on each use.
2. HTTP Basic Auth: Authorization: Basic base64(username:password). The username can be your account username or email address.
3. Query parameters: ?username=xxx&password=xxx. The username can be your account username or email.

For the /domains/update endpoint, only Basic Auth and query parameters are supported.

Query parameters

Parameter	Required	Description
hostname	Yes	The FQDN to update (e.g., myserver.certadns.com).
myip	No	The IP address to set. If omitted, auto-detected from the client's IP.
username	No	Your CertaDNS username or email (if not using header authentication).
password	No	Your account password or API key (if not using header authentication).

Using cURL or scripts

Example: Update with a specific IP using Basic Auth:

curl -u "username:api_key" \
  "https://www.certadns.com/domains/nic/update?hostname=myserver.certadns.com&myip=1.2.3.4"

Example: Auto-detect the IP from the client:

curl -u "username:api_key" \
  "https://www.certadns.com/domains/nic/update?hostname=myserver.certadns.com"

Example: Use Bearer token authentication:

curl -H "Authorization: Bearer ak_xxxxxxxxxxxxx" \
  "https://www.certadns.com/domains/nic/update?hostname=myserver.certadns.com"

Example: Use query parameters for authentication (not recommended for production due to credential exposure in logs):

curl "https://www.certadns.com/domains/nic/update?hostname=myserver.certadns.com&username=user&password=pass"

Configuring a router

Most routers support DynDNS2 protocol. Use these settings:

Setting	Value
Service / Provider	dyndns2 / Custom
Server / Hostname	www.certadns.com
Domain / Hostname	Your FQDN (e.g., myserver.certadns.com)
Username	Your CertaDNS username or email
Password	Your API key (recommended) or account password
Update URL / Path	/nic/update?hostname=%h&myip=%i

The %h placeholder is replaced by the hostname and %i is replaced by the detected IP. If your router does not support %i, omit &myip=%i and the server will auto-detect the IP.

Compatible routers include:

• Ubiquiti EdgeRouter / UniFi
• pfSense / OPNsense
• DD-WRT / OpenWRT
• ASUS RT-series
• Netgear routers with DDNS support
• TP-Link routers with DDNS support

Using the Update Help modal

1. Navigate to Dashboard > Domains.
2. Click the question mark icon in the Actions column for the domain you want to update.
3. The Update Help modal opens with two tabs: cURL / Script and Router.
4. On the cURL / Script tab:
   • Pre-filled cURL commands are displayed with your domain's FQDN already inserted.
   • Click the copy button next to each command to copy it to the clipboard. A checkmark appears for 2 seconds to confirm the copy.
   • If you do not have an API key, a message instructs you to generate one. A link to the API Keys page is provided.
   • Alternative endpoints (/v2/update, /dyndns/update) are listed with copy buttons.
5. On the Router tab:
   • A configuration table shows the exact values to enter in your router's DDNS settings.
   • A list of compatible routers is displayed.
   • A link to the full router setup guide (this page) is provided.

7. Inputs and Settings

Input	Description	Constraints
hostname	The FQDN of the domain to update.	Must exist in the authenticated user's domain list. Case-insensitive.
myip	The new IP address to assign.	Must be a valid IPv4 (for A records) or IPv6 (for AAAA records). If omitted, the client's IP is auto-detected.
username	Account username or email address.	Must match a registered user. Case-insensitive.
password	Account password or API key.	Must be correct for the specified username. API keys must be active.
Authorization header	Bearer token or Basic Auth credentials.	Bearer token format: Bearer ak_xxxxx. Basic Auth format: Basic base64(username:password).

IP auto-detection

If the myip parameter is omitted, the system extracts the client's IP in this order:

1. X-Forwarded-For header (first IP in the list).
2. request.client.host (fallback if header is missing).

This is useful for routers that use the %i placeholder or for clients behind proxies.

8. Outputs and Results

All responses follow the DynDNS protocol standard. The response body is plain text, not JSON.

Response	Meaning
good {IP}	Update successful. The IP was changed to the specified value.
nochg {IP}	IP unchanged. The submitted IP matches the current record value.
badauth	Authentication failed. Incorrect username, password, or API key, or the API key is inactive.
nohost	Domain not found, or the domain is not owned by the authenticated user.
dnserr	DNS or system error. PowerDNS sync failed or an internal error occurred.

HTTP status codes:

• 200 OK: Successful update or no change.
• 400 Bad Request: Invalid IP format or IPv4/IPv6 type mismatch.
• 401 Unauthorized: Authentication failed.
• 404 Not Found: Domain not found.
• 500 Internal Server Error: DNS sync error or internal failure.

IP detection endpoint

To query your current public IP without updating a domain, use the /domains/my-ip endpoint:

curl https://www.certadns.com/domains/my-ip

Response:

{
  "ip": "203.0.113.42"
}

No authentication is required for this endpoint.

9. How to Interpret Results

Normal

• good 1.2.3.4: The IP was successfully updated to 1.2.3.4. The DNS record now points to this address. External resolvers will see the new IP after the previous TTL expires (60 seconds on paid plans, 60 minutes on Free).
• nochg 1.2.3.4: The submitted IP (1.2.3.4) matches the current record. No update was performed. This is normal if your IP has not changed since the last update.

Unexpected or worth investigating

• badauth: Authentication credentials are incorrect. Verify your username, password, or API key. Check that the API key is active in the API Keys dashboard.
• nohost: The domain does not exist or is not owned by the authenticated user. Verify the hostname parameter exactly matches the FQDN in your dashboard (e.g., myserver.certadns.com, not myserver).
• dnserr: The update was accepted but failed to sync to PowerDNS. Check the domain's status in the dashboard. Contact support if the issue persists.
• 400 with error message: The IP format is invalid or does not match the record type. Example: submitting 2001:db8::1 for an A record returns 400 with a message indicating the mismatch.

Common interpretation mistakes

• Expecting instant DNS propagation: A good response means the authoritative DNS was updated, but caching resolvers will continue returning the old IP until the TTL expires. Query ns1.certadns.com or ns2.certadns.com directly to verify the authoritative answer.
• Confusing nochg with failure: nochg is a success response. It means the IP is already set to the submitted value. This is normal if your router sends updates on a schedule even when the IP has not changed.

10. Common Issues and Explanations

Router returns "badauth" error

The username or password is incorrect. Verify the username is your CertaDNS account username or email (not the domain name). If using an API key as the password, ensure the key is active in the API Keys dashboard. Some routers send the password in plaintext query parameters, which may be logged. Use an API key instead of your account password for better security.

"nohost" response even though domain exists

The hostname parameter must exactly match the FQDN, including the zone. For example, if your domain is myserver.certadns.com, the hostname parameter must be myserver.certadns.com, not myserver. Verify capitalization (though the check is case-insensitive). Ensure the domain is owned by the authenticated user.

IP update succeeds but external DNS lookups still return old IP

Caching DNS resolvers retain the previous answer until the TTL expires. On Free plans, TTL is 3600 seconds (60 minutes). On paid plans, TTL is 60 seconds. Query the authoritative name servers directly to verify the update:

dig @ns1.certadns.com myserver.certadns.com

"Invalid IP address" or "IPv4 required" error

A records require a valid IPv4 address (e.g., 192.0.2.1). AAAA records require a valid IPv6 address (e.g., 2001:db8::1). Submitting an IPv6 address for an A record (or vice versa) is rejected. Delete the domain and recreate it with the correct record type if you need to switch between IPv4 and IPv6.

Router does not support "%i" placeholder

Omit the &myip=%i parameter from the update URL. The server will auto-detect your public IP from the X-Forwarded-For header or the request source IP.

API key authentication returns "badauth" but password works

API key authentication requires a Plus, Pro, or Elite plan. Free users can only authenticate with username and password. Verify your plan in the dashboard. Ensure the API key is active (is_active=True) and has not been revoked.

Updates from router succeed but desktop client fails

The desktop client may be using a different authentication method or endpoint. Verify the client configuration matches the credentials and FQDN used in the router. Check the client's log files for detailed error messages.

11. Limits and Constraints

Constraint	Free	Plus	Pro	Elite
API key authentication	No	Yes	Yes	Yes
Username/password auth	Yes	Yes	Yes	Yes
Bearer token support	No	Yes	Yes	Yes
Update endpoints	All	All	All	All

• No explicit rate limit on update endpoints. However, excessive update requests (e.g., more than once per second) may trigger abuse detection.
• IP auto-detection relies on the X-Forwarded-For header. If the client is behind a proxy that does not set this header, the proxy's IP may be detected instead of the client's public IP.
• IPv4 addresses must not contain colons. IPv6 addresses must contain colons. The server validates IP format and rejects type mismatches.
• Hostnames are case-insensitive. MyServer.CertaDNS.net matches myserver.certadns.com.
• Maximum FQDN length: 253 characters.

12. Related Features

• Dynamic DNS Domains — The domains being updated by these protocols.
• API Keys — Generate keys for Bearer token authentication in update requests.
• Desktop Client — The CertaDNS client app uses these endpoints to update domains automatically.
• Uptime Monitoring — Monitor whether the IP assigned to a domain is reachable.
• DNS Analytics — View query volume and traffic patterns for updated domains.

13. Updates and Behavior Changes

• The /domains/nic/update endpoint now supports Bearer token authentication for API keys. Previously, only Basic Auth and query parameters were supported.
• IP auto-detection now prioritizes the X-Forwarded-For header over request.client.host to improve accuracy for clients behind proxies or load balancers.
• The /domains/my-ip endpoint was added to allow clients to query their public IP without performing an update.
• API key authentication is now available on Plus plans. Previously, it required Pro or Elite.
• The last_used_at timestamp for API keys is now updated on every update request, allowing users to track API key usage.