DDNS Update Protocols

Updating with your account email and password works on every Dynamic DNS plan. Updating with an API key needs Dynamic DNS Pro or Elite (or Email Authentication Enterprise), because that is where API keys are available.

1. What This Feature Does

Your router, NAS or a small script can keep a Dynamic DNS hostname pointed at your current IP address. It sends one HTTPS request to CertaDNS whenever your address changes, and CertaDNS updates the hostname's DNS record.

CertaDNS speaks the dyndns2 update protocol, the one most routers list as "DynDNS", "dyndns2" or "Custom". Scripts can also use the REST API.

2. When You Should Use It

• Your internet connection gets a new public IP address from time to time and you reach a device at home by name.
• Your router, firewall or NAS has a Dynamic DNS setting and you want it to keep the hostname current without you.
• You run a cron job or scheduled task that should update a hostname.

3. When You Should Not Use It

• The address never changes. Set it once in the dashboard under Dynamic DNS with Update IP.
• Your connection is behind carrier-grade NAT (the WAN address on your router is not your public address). The hostname will point at the right public address, but incoming connections will not reach your network.

4. Prerequisites

• A hostname in Dynamic DNS on your account. Updates only work for hostnames that belong to the account you sign in with.
• A verified account. Accounts that have not confirmed their email address, and suspended accounts, cannot update DNS.
• Either your account email address and password, or an API key from API Keys in the dashboard (Dynamic DNS Pro or Elite).

5. How It Works (Brief)

1. Your client sends the hostname and, optionally, the new address to the update URL, with your credentials.
2. If you leave the address out, CertaDNS uses the public address the request came from.
3. If the address differs from the one on record, the hostname's DNS record is changed and the answer is good. If it is the same, nothing changes and the answer is nochg.
4. Resolvers see the new address once the hostname's old answer expires from their cache: at most 60 seconds on Pro and Elite, and 3600 seconds (one hour) on Free.

6. How to Use It

Router or NAS (dyndns2)

In your device's Dynamic DNS settings, choose dyndns2, DynDNS or Custom and enter:

Routers send the username and password as HTTP Basic authentication. The password must be your account password: an API key entered as the password is refused with badauth.

ddclient

protocol=dyndns2
ssl=yes
server=www.certadns.com
login=you@example.com
password='your-account-password'
home.example.com

curl with an API key

Send a user agent that names your script, as these examples do with -A. Requests carrying a tool's default user agent may be refused before they reach the update service.

Send the key as a Bearer token. Leave out myip to use the address the request comes from:

curl -A "home-updater/1.0" -H "Authorization: Bearer YOUR_API_KEY" "https://www.certadns.com/nic/update?hostname=home.example.com"

Or set the address explicitly:

curl -A "home-updater/1.0" -H "Authorization: Bearer YOUR_API_KEY" "https://www.certadns.com/nic/update?hostname=home.example.com&myip=203.0.113.10"

curl with your account password

curl -A "home-updater/1.0" -u "you@example.com:your-account-password" "https://www.certadns.com/nic/update?hostname=home.example.com"

REST API (scripts)

With an API key you can also set the address with a JSON request. This form checks the address before saving it:

curl -A "home-updater/1.0" -X PUT "https://www.certadns.com/api/domains/fqdn/home.example.com" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"record_ip": "203.0.113.10"}'

The answer is JSON: {"fqdn": "home.example.com", "rrtype": "A", "record_ip": "203.0.113.10", "status": "success"}.

Find the instructions in the dashboard

In Dynamic DNS, the Update Instructions button (question-mark icon) on each hostname shows these settings with the hostname filled in.

7. Inputs and Settings

Update URLs

Use /nic/update unless your device needs one of the others. Putting your password in the URL (query parameters) is accepted only on /api/domains/nic/update, and only for devices that cannot send it any other way — URLs are often written to logs.

Parameters

Both go in the URL, for POST as well as GET. Other dyndns2 parameters (such as system, wildcard or mx) are ignored.

Credentials

An API key acts for the whole account; there are no per-key permissions. Create and revoke keys under API Keys; see API Keys.

8. Outputs and Results

The dyndns2 URLs answer in plain text:

A request without hostname is refused with HTTP 422 before any of these.

9. How to Interpret Results

Normal

• good after your address changes, then nochg on every check until it changes again.
• The dashboard's Current IP column shows the new address after a good.

Worth investigating

• good on every run with a different address each time — two devices are updating the same hostname, for example a router and a script on a different connection.
• A private address (192.168.x.x, 10.x.x.x) in Current IP — the client sent its local address in myip. Leave myip out, or use your router's WAN address.

Common mistakes

• Expecting the change instantly everywhere. Resolvers keep the old answer until it expires: up to 60 seconds on Pro and Elite, up to an hour on Free.
• Entering only the first part of the hostname (home instead of home.example.com). The answer is nohost.

10. Common Issues and Explanations

badauth with an API key

Send the key as Authorization: Bearer YOUR_API_KEY. A key entered in a router's password field is sent as Basic authentication, which only accepts your account password. Also check the key has not been revoked.

badauth with the right password

The username must be your account email address. If you have not confirmed your email address, confirm it first. A suspended account gets badauth too.

nohost

The hostname is misspelled, is not the full name, contains capitals, or belongs to a different account. If your client lists several hostnames in one request, set it up with one hostname per request.

badip

Check that myip is an IPv4 address for an A hostname or an IPv6 address for an AAAA hostname. For an AAAA hostname with myip left out, the request must itself be made over IPv6.

dnserr

The DNS change failed on our side. Nothing was stored; the next scheduled update will try again.

The address is right in the dashboard but a lookup still shows the old one

The old answer is cached. Wait for it to expire (see Limits below) and try again.

Updating a hostname that has web forwarding

The update is stored, and the answer is good, but the hostname keeps pointing at the forward. When you delete the forward, it points at the most recent address.

11. Limits and Constraints

12. Related Features

• Dynamic DNS — creating hostnames and changing their address in the dashboard.
• API Keys — creating and revoking the keys used above.
• Wildcard Hostnames — a wildcard is a hostname of its own and is updated separately.
• Web Forwarding — what updates do to a forwarded hostname.

13. Updates and Behavior Changes

• 30 September 2026. API keys now work on the router update URLs (/nic/update, /v2/update, /dyndns/update) when sent as a Bearer token. Before this date they were refused with badauth. An API key is still not accepted as a Basic-authentication password.
• 30 September 2026. Accounts that have not confirmed their email address, and suspended accounts, get badauth from every update URL.
• 30 September 2026. Earlier versions of this article listed update paths beginning /domains/, which are not served, said an API key could be used as a Basic-authentication password, and described API-key scopes, which do not exist.
• 1 October 2026. An address that is not valid for the hostname is refused with badip instead of being stored. A failed DNS change stores nothing, so the next update retries rather than answering nochg. Updates to a forwarded hostname no longer switch the forward off.