Open standard for Dynamic DNS services.
The ApertoDNS Protocol is an open standard that provides:
- Modern JSON API with structured responses and error handling
- Full DynDNS2 compatibility for legacy clients (routers, ddclient, etc.)
- Native IPv6 support alongside IPv4
- TXT record support for ACME DNS-01 challenges (RFC 8555)
- Webhook notifications for IP change events
- Health check and domain listing endpoints
- GDPR compliance (provider-specific, not part of protocol)
- Security first design with TLS 1.2+ requirement
- Protocol Specification v1.4.0 - Complete protocol specification
- OpenAPI Specification - OpenAPI 3.0.3 schema (View in Swagger Editor)
- Security Policy - Security requirements and vulnerability reporting
- Changelog - Version history
- Adopters - Providers implementing this protocol
Use the official TypeScript client:
npm install apertodns-clientimport { ApertoDNSClient } from 'apertodns-client';
const client = new ApertoDNSClient({
token: 'apertodns_live_xxxxxxxxxxxxxxxxxxxxxxxxxx'
});
const result = await client.update({
hostname: 'home.example.com',
ipv4: 'auto'
});- Read the Protocol Specification
- Implement the required endpoints (Layers 0, 1, 2)
- Run the conformance tests
- Submit a PR to be listed in ADOPTERS.md
| Layer | Name | Required | Description |
|---|---|---|---|
| 0 | Transport Security | Yes | HTTPS, TLS 1.2+, HSTS |
| 1 | Legacy Compatibility | Yes | DynDNS2 /nic/update endpoint |
| 2 | Modern API | Yes | REST endpoints under /.well-known/apertodns/v1/ |
| 3 | Extended Features | No | Webhooks, bulk operations, token management |
Providers implementing ApertoDNS Protocol v1.3.0+ support TXT record management for ACME DNS-01 certificate validation:
# Using acme.sh (when dns_apertodns plugin is available)
export APERTODNS_Url="https://api.your-provider.com"
export APERTODNS_Token="your_api_token"
acme.sh --issue -d home.example.com --dns dns_apertodns
# Manual API usage
curl -X POST "https://api.your-provider.com/.well-known/apertodns/v1/txt" \
-H "Authorization: Bearer your_token" \
-H "Content-Type: application/json" \
-d '{"hostname":"_acme-challenge.home.example.com","value":"acme-challenge-token"}'See Section 7: TXT Records in the protocol specification.
Run the included test suite to verify your implementation:
cd tests
npm install
export APERTODNS_TEST_URL="https://api.your-provider.com"
export APERTODNS_TEST_TOKEN="your_api_key"
npm testSee tests/README.md for full documentation.
- Provider: ApertoDNS
- Client: apertodns-client (npm)
Contributions are welcome! Please read the protocol specification before proposing changes.
This protocol maintains compatibility with the DynDNS2 protocol (/nic/update), which is a de facto industry standard used by routers, NAS devices, and DDNS clients worldwide. DynDNS® is a registered trademark of Oracle Corporation. ApertoDNS is not affiliated with Oracle or Dyn.
MIT License - Copyright (c) 2025 Andrea Ferro