API Keys

Available on: Pro Elite

1. What This Feature Does

API Keys provide programmatic access to CertaDNS's API and DDNS update endpoints. Keys are used as Bearer tokens in HTTP Authorization headers. They enable router-based DDNS updates, scripted IP changes, and integration with third-party tools without exposing account passwords.

Each key is a cryptographically secure token generated server-side. Keys can authenticate API requests for domain creation, updates, and management. They can also be used with DDNS update protocols in place of account passwords. Each key tracks its last usage timestamp for auditing purposes.

API Keys are available on Pro and Elite plans only. Free and Plus users who attempt to access the API Keys feature receive a 403 error and an upgrade prompt.

2. When You Should Use It

• You need to update DDNS domains from a router or client that supports HTTP authentication but you do not want to store your account password in the device configuration.
• You are scripting domain updates or IP changes and need a credential that can be revoked independently of your account password.
• You are integrating CertaDNS with third-party automation tools (CI/CD pipelines, monitoring systems, orchestration platforms) that require API access.
• You want to isolate API access for security: if a key is compromised, you can deactivate it without changing your account password.
• You need multiple credentials for different applications or environments and want to track which client last used which key.

3. When You Should Not Use It

• Manual dashboard access: API keys are for programmatic access only. Use your account password to log in to the web dashboard.
• Free or Plus plan: API Keys are not available on Free or Plus plans. Attempting to access the feature on these plans results in an upgrade prompt.
• Two-factor authentication enforcement: API keys bypass 2FA. If your security policy requires interactive 2FA for all access, do not use API keys. Use account credentials with 2FA enabled instead.
• Shared accounts: If multiple users share a single account, API keys do not provide per-user attribution. Consider using separate accounts with individual keys for accountability.

4. Prerequisites

• An active CertaDNS account on the Pro or Elite plan.
• Verified email address on the account.
• Access to the dashboard (web or desktop client).
• A secure location to store the key value after creation (password manager, environment variable, configuration management system).

5. How It Works (Brief)

When you create an API key, the server generates a 32-byte cryptographically secure token using secrets.token_urlsafe(32) (base64url encoding). The key is prefixed with ak_ for identification. The full key value is returned once and never retrievable again. The system stores a hashed version of the key for authentication.

When you make an API request with the key in the Authorization: Bearer ak_... header, the server hashes the provided key and compares it to the stored hash. If the hashes match and the key is active, the request is authenticated. The last_used_at timestamp is updated on each successful authentication.

Keys can be deactivated (soft delete) at any time. Deactivated keys set is_active=False and immediately stop authenticating requests. Deactivation is permanent; deactivated keys cannot be reactivated.

6. How to Use It

Creating an API key

1. Navigate to Dashboard > Account > API Keys.
2. Click Create API Key in the top right. (This button is disabled if you have reached the 5-key limit.)
3. In the Create API Key modal:
   • Enter a name for the key. This is a label for your reference (e.g., "Home Router", "CI/CD Pipeline").
4. Click Create Key.
5. The key value is displayed once in a second modal with a prominent warning: "This is the only time you will see this key."
6. Click Copy to Clipboard to copy the key value.
7. Store the key in a secure location (password manager, environment variable, secrets vault).
8. Click I've saved my key to confirm. The key value is hidden permanently after this confirmation.

Using an API key

Include the key in the Authorization header of HTTP requests as a Bearer token:

Authorization: Bearer ak_your_api_key_here

Example: Create a new domain using curl:

curl -X POST https://www.certadns.com/api/domains \
  -H "Authorization: Bearer ak_dGVzdF9rZXlfZm9yX2V4YW1wbGU..." \
  -H "Content-Type: application/json" \
  -d '{
    "fqdn": "myserver.certadns.com",
    "record_type": "A",
    "record_ip": "192.168.1.100"
  }'

Example: Update a domain's IP using curl:

curl -X PUT https://www.certadns.com/api/domains/fqdn/myserver.certadns.com \
  -H "Authorization: Bearer ak_dGVzdF9rZXlfZm9yX2V4YW1wbGU..." \
  -H "Content-Type: application/json" \
  -d '{"record_ip": "10.0.0.1"}'

API keys are also supported as Basic Auth passwords on DDNS update endpoints (/domains/nic/update, /domains/v2/update, /domains/dyndns/update). Use your account username and the API key as the password.

Viewing API keys

1. Navigate to Dashboard > Account > API Keys.
2. The key list displays all active and inactive keys with metadata:
   • Name: The label you provided when creating the key.
   • Created: Timestamp of key creation.
   • Last Used: Timestamp of the most recent successful authentication using this key, or "Never" if the key has not been used.

Deactivating an API key

1. In the API Keys list, find the key you want to deactivate.
2. Click the trash icon in the Actions column.
3. Confirm the deletion in the dialog. The key is immediately deactivated and will no longer authenticate requests.

Deactivated keys are soft-deleted (set is_active=False) and remain in the database for audit purposes, but they are removed from the key list in the UI. Deactivation is permanent and cannot be undone. If you need the same key again, create a new one.

7. Inputs and Settings

Field	Description	Constraints
Name	A descriptive label for the key (e.g., "Production Server", "Test Environment").	Required. Maximum 255 characters. Used for identification only; does not affect authentication.

Key format

• Prefix: ak_
• Body: 32 bytes, base64url encoded (from secrets.token_urlsafe(32)).
• Example: ak_dGVzdF9rZXlfZm9yX2V4YW1wbGU...
• Total length: approximately 47 characters.

Key storage

The key value is displayed once immediately after creation. The server does not store the plaintext key. Only a hashed version is retained for authentication. If you lose the key value, you must deactivate the old key and create a new one.

8. Outputs and Results

API key list columns

Column	Description
Name	The label you provided during creation.
Created	ISO 8601 timestamp of key creation.
Last Used	ISO 8601 timestamp of the most recent successful authentication, or "Never" if unused.
Actions	Delete (trash icon) to deactivate the key.

API response on creation

The POST /api-keys/ endpoint returns:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": 123,
  "key": "ak_dGVzdF9rZXlfZm9yX2V4YW1wbGU...",
  "name": "Home Router",
  "created_at": "2025-01-15T10:30:00Z",
  "last_used_at": null,
  "is_active": true
}

The key field is only present in this creation response. Subsequent GET requests return metadata only (no key field).

API response on list

The GET /api-keys/ endpoint returns:

{
  "keys": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Home Router",
      "created_at": "2025-01-15T10:30:00Z",
      "last_used_at": "2025-01-20T14:22:10Z",
      "is_active": true
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "CI Pipeline",
      "created_at": "2025-01-10T08:15:00Z",
      "last_used_at": null,
      "is_active": true
    }
  ]
}

9. How to Interpret Results

Normal

• Key appears in the list with a "Created" timestamp matching when you created it.
• After first use, "Last Used" updates to the timestamp of the most recent API request authenticated with the key.
• API requests authenticated with the key receive normal responses (200, 201, etc.) based on the endpoint logic.

Unexpected or worth investigating

• "Last Used" timestamp is recent but you did not make a request: Another user or application may have access to the key. Deactivate the key immediately and create a new one. Review where the key is stored and who has access.
• "Last Used" shows "Never" for a key you are actively using: Verify the key value is correct. Check that the Authorization header format is Bearer ak_... with no extra spaces or characters. Review server logs for authentication failures.
• API request returns 401 Unauthorized: The key may be deactivated, incorrect, or not included in the request header. Verify the key is active in the dashboard and the header syntax is correct.

Common interpretation mistakes

• Expecting to retrieve the key value later: The key value is shown once on creation and cannot be retrieved afterward. If you lose it, you must deactivate the old key and create a new one.
• Confusing "Last Used" with "Last Created": "Last Used" reflects authentication activity, not creation or modification timestamps. A key created recently but never used shows "Never".
• Assuming deactivation is reversible: Deactivating a key is permanent. The key cannot be reactivated. You must create a new key if you need access again.

10. Common Issues and Explanations

403 error: "API access requires Pro or Elite subscription"

API Keys are only available on Pro and Elite plans. Free and Plus users receive this error when attempting to access the API Keys page or create a key. Upgrade to Pro or Elite to use this feature.

400 error: "Maximum number of API keys reached (5)"

You have created the maximum of 5 API keys. Deactivate an unused key before creating a new one. Deactivation is immediate and frees a slot for a new key.

404 error: "API key not found" on delete

The key ID does not exist or has already been deactivated. Refresh the key list to verify the current state. This error typically occurs if you attempt to deactivate the same key twice or if the key was deactivated by another session.

401 Unauthorized when using an API key in requests

Verify the key is active in the dashboard. Check the Authorization header format: it must be Authorization: Bearer ak_... with the exact key value, no extra spaces. Ensure the key has not been deactivated. If the key was lost or compromised, create a new one.

"Create API Key" button is disabled

You have reached the 5-key limit. Deactivate an existing key to enable the button. The button also remains disabled if your account is not on a Pro or Elite plan.

Key value not visible after closing the creation modal

The key value is shown once for security reasons and cannot be retrieved after you confirm saving it. If you did not copy the key, you must deactivate the unusable key and create a new one.

API key authenticates successfully but request fails with 403 or 404

Authentication succeeded, but the request itself was rejected due to authorization (insufficient plan tier, domain not found, etc.). Review the specific error message returned by the API. API keys authenticate identity but do not bypass plan limits or resource ownership rules.

11. Limits and Constraints

Constraint	Value
Maximum keys per account	5
Plans with access	Pro, Elite only
Key retrieval after creation	Not possible (shown once)
Key reactivation after deactivation	Not possible (permanent)
Key name maximum length	255 characters

• Keys are scoped to the account. An API key authenticates as the account owner and has access to all resources the account owns.
• API keys bypass two-factor authentication. If 2FA is enabled on the account, API key authentication does not require a TOTP code.
• Deactivated keys are soft-deleted (set is_active=False) and retained in the database for audit purposes but are not visible in the UI and cannot authenticate requests.
• The last_used_at timestamp is updated on each successful API request authenticated with the key. It does not update on failed authentication attempts.

12. Related Features

• DDNS Update Protocols — API keys authenticate router and script updates to DDNS endpoints.
• Dynamic DNS Domains — API keys enable programmatic domain creation and IP updates.
• Two-Factor Authentication — Note that API keys bypass 2FA when authenticating API requests.
• Account Security — Best practices for managing credentials, including API keys.

13. Updates and Behavior Changes

• API Keys were introduced as a Pro and Elite feature to support secure programmatic access without exposing account passwords.
• The maximum key limit per account is 5. This limit may be adjusted in future updates based on user feedback.
• Keys use secrets.token_urlsafe(32) for cryptographic security. The prefix ak_ was added to distinguish API keys from other token types in logs and configuration files.