API Keys

Included with Dynamic DNS Pro and Elite, and with Email Authentication Enterprise.

1. What This Feature Does

An API key lets a script, a router or another system act on your account without your password. Each key:

• Starts with ak_ and is shown to you once, when you create it.
• Is stored by CertaDNS only as a one-way hash, so nobody — including CertaDNS — can show it to you again.
• Can be deleted at any time; anything using it stops working immediately.
• Records when it was last used.

2. When You Should Use It

• A script or scheduled job updates your Dynamic DNS hostnames.
• A router or update client can send an Authorization: Bearer header, and you do not want your account password stored on it.
• You want a separate credential per device or job, so you can cut one off without touching the others or your password.

3. When You Should Not Use It

• Signing in to the dashboard. Keys do not work at the sign-in page; use your email address and password.
• Router DDNS clients that only have username and password fields. Those send your credentials as Basic authentication, which accepts your account email and password, not an API key. See DDNS Update Protocols.
• Changing Email Authentication settings, Managed DNS zones and records, TLS certificates, billing and account settings. These are managed in the dashboard only. Email Authentication data can be read with the Email Authentication API.
• Accounts managed by an organization. Members of an organization cannot create personal API keys; ask the organization owner.

4. Prerequisites

• Dynamic DNS Pro or Elite, or Email Authentication Enterprise.
• A place to keep the key safely the moment it is shown — a password manager or your system's secret store.

5. How It Works (Brief)

When you create a key, CertaDNS generates it, shows it to you once, and keeps only a hash of it. When a request presents the key, CertaDNS hashes what was sent and looks for an active key with that hash. If it finds one, the request runs as your account and the key's last-used time is updated.

An API key acts as you: it can do whatever your account can do through the endpoints that accept keys. It does not ask for a two-factor code.

6. How to Use It

Keys are managed in Account > API Keys in the dashboard sidebar. The same list is also under Settings > API keys.

Create a key

1. Click Create new key.
2. Enter a Key Name that says where it will be used (for example Home router or Backup script), then click Create Key.
3. The API Key Created panel shows the full key once. Click the copy icon and store it straight away.
4. Click Done. From now on the list shows only the key's name and dates.

Present a key

Send the key in the Authorization header, as a Bearer token:

Authorization: Bearer ak_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• Dashboard API (paths under https://www.certadns.com/api/): the header must read exactly Bearer ak_ followed by the rest of the key — the word Bearer with a capital B, one space, and the whole key including its ak_ prefix.
• Router update URLs (/nic/update, GET and POST, /v2/update and /dyndns/update): the same header, Bearer followed by one space and the key.
• Keys are not accepted as a query parameter, a cookie, or the password in Basic authentication.

For example, to point a Dynamic DNS hostname at a new address:

GET https://www.certadns.com/nic/update?hostname=home.example.com&myip=203.0.113.10
Authorization: Bearer ak_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Leave out myip and the address the request came from is used.

What a key can reach

• The router update URLs above.
• Your Dynamic DNS hostnames: create, list, update and delete — for example PUT /api/domains/fqdn/<hostname> with the body {"record_ip": "203.0.113.10"}.
• Wildcard hostnames, web forwarding and vanity nameservers.
• Uptime monitoring, DNS analytics, DNS failover, threat detection, reports and notifications.

Delete a key

1. Click the trash icon on the key.
2. Confirm with Delete key. Anything using the key stops working immediately. This cannot be undone.

Replace a lost or exposed key

1. Create a new key and store it.
2. Put the new key into every device or script that used the old one.
3. Delete the old key.

If the old key may have leaked, delete it first and accept a short gap in updates.

7. Inputs and Settings

A key is ak_ followed by 43 letters, digits, hyphens and underscores — 46 characters in all. Keys have no scopes and no expiry date: every key has the same access, and it works until you delete it.

8. Outputs and Results

The key list

• Name — the label you gave the key.
• Created — the date it was created.
• Last used — the date of the last request it authenticated, shown once it has been used.
• A counter, n of 5 used.

The key itself is never shown in the list. Deleted keys disappear from it.

Router update responses

9. How to Interpret Results

Normal

• Last used moves forward each time the device or script runs.
• A new key shows no last-used date until its first request.

Worth investigating

• A recent last-used date on a key you thought was idle. Something still holds it. If you cannot account for it, delete the key.
• No last-used date on a key you are using. Its requests are not being accepted — check the header as described below.

10. Common Issues and Explanations

"API access is included with Dynamic DNS Pro and with the Email Authentication Enterprise tier."

Your account has neither. Upgrade to create keys.

"Personal API keys aren't available on org-managed accounts."

Your account belongs to an organization. Ask the organization owner if API access is needed.

"Maximum number of API keys reached (5)"

You have five keys. Delete one you no longer use; the slot is free immediately.

"Please enter a name for the API key"

The name is required.

"API key not found"

The key was already deleted, for example in another browser tab. Refresh the list.

badauth from a router update URL, or "Authentication required" from the dashboard API

• The header is not Authorization: Bearer ak_… — for example the key was put in the password field, ak_ was left off, or bearer is lower-case.
• The key was deleted, or was copied incompletely.
• The account is not active — for example its email address has not been confirmed.

I have lost the key

It cannot be shown again. Create a new key, update whatever used the old one, and delete the old one.

The key works but the request is refused

The key identified you, but the action is not allowed — the hostname belongs to someone else, a plan limit applies, or that part of the product does not accept keys (see section 3). Read the error message the request returned.

11. Limits and Constraints

• Your plan is checked when a key is created, not when it is used. A key you created on Pro keeps working if you later leave Pro, so delete keys you no longer need.
• If your account is disabled, its keys stop working.

12. Related Features

• DDNS Update Protocols — configuring routers and update clients.
• Dynamic DNS Domains — the hostnames a key updates.
• Two-Factor Authentication — protects dashboard sign-in; keys do not use it.
• Account & Subscription Management — the plans that include API access.

13. Updates and Behavior Changes

• 30 September 2026. API keys now work on the router update URLs (/nic/update, /v2/update and /dyndns/update) when sent as Authorization: Bearer. Before this, those URLs answered badauth to every API key. Earlier versions of this article also said a key could be used as the password in Basic authentication; that has never worked.
• 1 October 2026. Keys have access chosen when they are created — Dynamic DNS, or the read-only Email Authentication API — an optional list of domains, and an expiry date (one year by default). Expired keys stop working; before this date the expiry was not enforced.
• September 2026. Email Authentication Enterprise includes API access, alongside Dynamic DNS Pro and Elite.