ApertoDNS Protocol: A Modern Dynamic DNS Update Protocol

1.1. Protocol Versioning

The protocol version specified in discovery responses (e.g., "1.3.0") refers to the semantic version of the protocol specification itself. This document represents the first IETF standardization of a protocol that has been in production use since 2024. The version number in the discovery endpoint reflects the feature set available, while the Internet-Draft version (e.g., "-01") tracks the IETF document revision process separately.¶

1.2. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.3. Goals

The ApertoDNS Protocol is designed with the following goals:¶

• Provider-agnostic: Any DDNS provider can implement this protocol using their own domain and branding¶

• Secure by default: HTTPS required, bearer token authentication¶

• Modern: JSON responses, proper HTTP semantics, native IPv6¶

• Discoverable: Self-describing via discovery endpoint¶

• Extensible: Capability negotiation allows future enhancements¶

• Backward compatible: Optional legacy endpoint for existing clients¶

3.1. Base URL

Conforming implementations MUST serve all endpoints under:¶

https://{provider-domain}/.well-known/apertodns/v1/

The use of well-known URIs [RFC8615] ensures consistent endpoint discovery across providers.¶

3.2. Content Type

All request and response bodies MUST use the application/json media type [RFC8259] unless otherwise specified.¶

3.3. Response Format

All responses MUST include a boolean success field at the top level:¶

{
  "success": true,
  "data": { ... }
}

Or for errors:¶

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

4.1. Conformance Levels

This protocol defines two conformance levels:¶

Core Conformance:

A conforming implementation MUST implement the following endpoints: /info, /health, and /update. A conforming implementation MUST support bearer token authentication. A conforming implementation MUST serve all endpoints over HTTPS.¶

Full Conformance:

In addition to core conformance requirements, a fully conforming implementation MUST implement: /bulk-update, /status/{hostname}, and /domains endpoints.¶

4.2. Capability Advertisement

Implementations MUST accurately advertise their capabilities in the /info endpoint response. Implementations MUST NOT advertise capabilities they do not support.¶

4.3. Interoperability

Implementations SHOULD accept requests from any conforming client. Implementations MUST NOT require proprietary extensions for basic DDNS functionality.¶

5.1. Supported Methods

Protected endpoints require authentication via one of the following methods:¶

1. Bearer Token (RECOMMENDED) [RFC6750]: Authorization: Bearer {token}¶

2. API Key Header: X-API-Key: {token}¶

3. HTTP Basic (legacy only): Authorization: Basic {credentials}¶

Implementations MUST support bearer token authentication. Implementations MAY support additional methods.¶

5.2. Token Format

Tokens SHOULD follow the format:¶

{provider}_{environment}_{random}

Where:¶

• {provider}: Provider identifier (e.g., "apertodns", "example")¶

• {environment}: Token environment ("live", "test", "sandbox")¶

• {random}: Cryptographically secure random string (minimum 32 characters recommended)¶

Example: apertodns_live_Kj8mP2xL9nQ4wR7vY1zA3bC6dE0fG5hI¶

This format enables:¶

• Easy identification of token source during debugging¶

• Environment separation (production vs. testing)¶

• Consistent token handling across providers¶

5.3. Token Transmission

Tokens MUST be transmitted only in HTTP headers. Tokens MUST NOT appear in URLs, query parameters, or request bodies where they might be logged.¶

6.1. Discovery Endpoint (/info)

GET /.well-known/apertodns/v1/info

The discovery endpoint returns provider information, capabilities, and configuration. This endpoint MUST NOT require authentication.¶

{
  "success": true,
  "data": {
    "protocol": "apertodns",
    "protocol_version": "1.3.0",
    "provider": {
      "name": "Example DDNS",
      "website": "https://example.com",
      "documentation": "https://example.com/docs",
      "support_email": "support@example.com"
    },
    "capabilities": {
      "ipv4": true,
      "ipv6": true,
      "auto_ip_detection": true,
      "bulk_update": true,
      "webhooks": true,
      "max_bulk_size": 100
    },
    "authentication": {
      "methods": ["bearer_token", "api_key_header"],
      "token_format": "{provider}_{environment}_{random}"
    },
    "endpoints": {
      "info": "/.well-known/apertodns/v1/info",
      "health": "/.well-known/apertodns/v1/health",
      "update": "/.well-known/apertodns/v1/update",
      "bulk_update": "/.well-known/apertodns/v1/bulk-update",
      "status": "/.well-known/apertodns/v1/status/{hostname}",
      "domains": "/.well-known/apertodns/v1/domains"
    },
    "rate_limits": {
      "update": {"requests": 60, "window_seconds": 60},
      "bulk_update": {"requests": 10, "window_seconds": 60}
    },
    "server_time": "2025-01-01T12:00:00.000Z"
  }
}

6.2. Health Endpoint (/health)

GET /.well-known/apertodns/v1/health

Returns service health status. This endpoint MUST NOT require authentication and SHOULD be used for monitoring.¶

{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2025-01-01T12:00:00.000Z"
  }
}

6.3. Update Endpoint (/update)

POST /.well-known/apertodns/v1/update
Authorization: Bearer {token}
Content-Type: application/json

Updates DNS records for a single hostname. This endpoint MUST require authentication.¶

{
  "hostname": "home.example.com",
  "ipv4": "auto",
  "ttl": 300
}

{
  "success": true,
  "data": {
    "hostname": "home.example.com",
    "ipv4": "203.0.113.50",
    "previous_ipv4": "203.0.113.49",
    "ttl": 300,
    "changed": true,
    "timestamp": "2025-01-01T12:00:00.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "ipv4_auto_failed",
    "message": "Cannot auto-detect IPv4 from IPv6 connection"
  }
}

6.4. Bulk Update Endpoint (/bulk-update)

POST /.well-known/apertodns/v1/bulk-update
Authorization: Bearer {token}
Content-Type: application/json

Updates multiple hostnames in a single request. Providers advertising bulk_update: true in capabilities MUST implement this endpoint.¶

{
  "updates": [
    {"hostname": "home.example.com", "ipv4": "auto"},
    {"hostname": "office.example.com", "ipv4": "203.0.113.51"}
  ]
}

{
  "success": true,
  "data": {
    "summary": {
      "total": 2,
      "successful": 2,
      "failed": 0
    },
    "results": [
      {
        "hostname": "home.example.com",
        "success": true,
        "ipv4": "203.0.113.50",
        "changed": true
      },
      {
        "hostname": "office.example.com",
        "success": true,
        "ipv4": "203.0.113.51",
        "changed": true
      }
    ]
  }
}

6.5. Status Endpoint (/status/{hostname})

GET /.well-known/apertodns/v1/status/{hostname}
Authorization: Bearer {token}

Returns current DNS record status for a hostname.¶

{
  "success": true,
  "data": {
    "hostname": "home.example.com",
    "ipv4": "203.0.113.50",
    "ipv6": "2001:db8::1",
    "ttl": 300,
    "last_updated": "2025-01-01T12:00:00.000Z"
  }
}

6.6. Domains Endpoint (/domains)

GET /.well-known/apertodns/v1/domains
Authorization: Bearer {token}

Returns list of domains and hostnames available to the authenticated user.¶

{
  "success": true,
  "data": {
    "domains": [
      {
        "domain": "example.com",
        "hostnames": ["home.example.com", "office.example.com"]
      }
    ]
  }
}

6.7. TXT Record Endpoint (/txt)

The TXT record endpoint enables management of DNS TXT records, primarily for ACME DNS-01 challenges [RFC8555] used in automated certificate issuance. Providers advertising txt_records: true in capabilities MUST implement this endpoint.¶

POST /.well-known/apertodns/v1/txt
Authorization: Bearer {token}
Content-Type: application/json

{
  "hostname": "_acme-challenge.home.example.com",
  "value": "gfj9Xq...Rg85nM",
  "ttl": 60
}

{
  "success": true,
  "data": {
    "hostname": "_acme-challenge.home.example.com",
    "value": "gfj9Xq...Rg85nM",
    "ttl": 60,
    "record_count": 1,
    "timestamp": "2026-01-01T12:00:00.000Z"
  }
}

DELETE /.well-known/apertodns/v1/txt
Authorization: Bearer {token}
Content-Type: application/json

{
  "hostname": "_acme-challenge.home.example.com",
  "value": "gfj9Xq...Rg85nM"
}

{
  "success": true,
  "data": {
    "hostname": "_acme-challenge.home.example.com",
    "deleted": true,
    "values_removed": 1,
    "remaining_count": 1,
    "timestamp": "2026-01-01T12:00:00.000Z"
  }
}

GET /.well-known/apertodns/v1/txt/{hostname}
Authorization: Bearer {token}

{
  "success": true,
  "data": {
    "hostname": "_acme-challenge.home.example.com",
    "values": [
      "gfj9Xq...Rg85nM",
      "hK7pLm...Yt42xQ"
    ],
    "ttl": 60,
    "record_count": 2
  }
}

7.1. HTTP Status Codes

Implementations MUST use appropriate HTTP status codes as defined in [RFC9110]:¶

7.2. Error Response Format

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

7.3. Standard Error Codes

7.4. Rate Limiting Headers

When rate limiting is applied, responses SHOULD include:¶

• Retry-After: Seconds until rate limit resets¶

• X-RateLimit-Limit: Maximum requests per window¶

• X-RateLimit-Remaining: Remaining requests in window¶

• X-RateLimit-Reset: Unix timestamp when window resets¶

8.1. Legacy Response Codes

Responses MUST be plain text (not JSON):¶

This endpoint is provided for compatibility only. New implementations SHOULD use the modern JSON endpoints.¶

10.1. Transport Security

All endpoints MUST be served over HTTPS using TLS 1.2 or higher. Implementations MUST NOT support plaintext HTTP for any protocol endpoint.¶

Implementations SHOULD support TLS 1.3 and SHOULD disable older cipher suites known to be weak.¶

10.2. Token Security

• Tokens MUST be generated using cryptographically secure random number generators (CSPRNG)¶

• Tokens SHOULD have configurable expiration¶

• Providers SHOULD support token revocation¶

• Tokens MUST NOT be logged in server access logs¶

• Tokens MUST NOT appear in URLs or error messages¶

10.3. Hostname Validation

Before processing any update request, implementations MUST verify that the authenticated user owns or has permission to modify the requested hostname. Failure to validate ownership could allow unauthorized DNS modifications.¶

10.4. Rate Limiting

Providers SHOULD implement rate limiting to prevent:¶

• Brute-force token guessing¶

• Denial of service attacks¶

• Excessive DNS propagation load¶

Rate limits SHOULD be advertised in the discovery endpoint and communicated via response headers.¶

10.5. DNS Rebinding Prevention

Implementations MUST validate that IP addresses in update requests are not private, loopback, or link-local addresses unless explicitly configured to allow such addresses.¶

10.6. Input Validation

All user input MUST be validated:¶

• Hostnames MUST conform to DNS naming rules¶

• IP addresses MUST be valid IPv4 or IPv6 format¶

• TTL values MUST be within acceptable ranges¶

• TXT values MUST NOT exceed 255 characters¶

10.7. TXT Record Abuse Prevention

TXT records can potentially be abused for:¶

• DNS tunneling: Encoding data in TXT records for covert communication¶

• Data exfiltration: Using DNS queries to leak sensitive data¶

• Resource exhaustion: Creating excessive TXT records¶

Implementations MUST implement safeguards:¶

• Limit TXT value length to 255 characters (DNS standard)¶

• Limit number of TXT records per hostname (default: 5)¶

• Restrict TXT hostnames to approved prefixes (e.g., _acme-challenge.)¶

• Implement rate limiting on TXT operations¶

• Consider automatic expiration of TXT records (recommended: 24 hours)¶

10.8. Internationalized Domain Names

When handling Internationalized Domain Names (IDNs), the following requirements apply as specified in [RFC5891]:¶

• Clients SHOULD convert IDN hostnames to their A-label (ASCII Compatible Encoding) form before sending requests¶

• Servers MUST accept hostnames in A-label form¶

• Servers MAY accept hostnames in U-label (Unicode) form and convert them to A-labels internally¶

• Servers MUST store and return hostnames in a consistent form¶

For example, a client wishing to update the hostname "例え.example.com" SHOULD send the request with the A-label form "xn--r8jz45g.example.com".¶

Implementations that accept U-label input MUST perform IDNA2008 validation as specified in [RFC5891] before processing the request.¶

11.1. Data Minimization

Providers SHOULD minimize the collection and retention of personal data. Specifically:¶

• IP address history SHOULD have configurable retention periods¶

• Update timestamps MAY be retained for operational purposes¶

• Providers SHOULD document their data retention policies¶

11.2. User Control

Users SHOULD have mechanisms to:¶

• View their stored data¶

• Delete their accounts and associated data¶

• Export their data in a portable format¶

11.3. Traffic Analysis

DDNS updates inherently reveal:¶

• That a user's IP address has changed¶

• The timing of IP address changes¶

• The association between a hostname and IP address¶

Providers should be aware that this information could be used to track user behavior or network changes.¶

11.4. Encryption

All communications MUST be encrypted via HTTPS, preventing passive observation of update requests and tokens.¶

12.1. Well-Known URI Registration

This document requests registration of the following well-known URI suffix:¶

URI Suffix:

apertodns¶

Change Controller:

IETF¶

Specification Document:

This document¶

Related Information:

None¶

The well-known URI /.well-known/apertodns/ is used as the base path for all protocol endpoints.¶

13.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC5891]

Klensin, J., "Internationalized Domain Names in Applications (IDNA): Protocol", RFC 5891, DOI 10.17487/RFC5891, August 2010, <https://www.rfc-editor.org/rfc/rfc5891>.

[RFC6750]

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, <https://www.rfc-editor.org/rfc/rfc6750>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

[RFC8555]

Barnes, R., Hoffman-Andrews, J., McCarney, D., and J. Kasten, "Automatic Certificate Management Environment (ACME)", RFC 8555, DOI 10.17487/RFC8555, March 2019, <https://www.rfc-editor.org/rfc/rfc8555>.

[RFC8615]

Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019, <https://www.rfc-editor.org/rfc/rfc8615>.

[RFC9110]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/rfc/rfc9110>.

13.2. Informative References

[RFC2136]

Vixie, P., Ed., Thomson, S., Rekhter, Y., and J. Bound, "Dynamic Updates in the Domain Name System (DNS UPDATE)", RFC 2136, DOI 10.17487/RFC2136, April 1997, <https://www.rfc-editor.org/rfc/rfc2136>.

[RFC6973]

Cooper, A., Tschofenig, H., Aboba, B., Peterson, J., Morris, J., Hansen, M., and R. Smith, "Privacy Considerations for Internet Protocols", RFC 6973, DOI 10.17487/RFC6973, July 2013, <https://www.rfc-editor.org/rfc/rfc6973>.

B.1. ApertoDNS

Organization:

ApertoDNS¶

Implementation:

Reference implementation¶

Description:

Full protocol support including all endpoints, bulk updates, webhooks, and legacy compatibility¶

Level of Maturity:

Production¶

Coverage:

Complete¶

Licensing:

Proprietary service, open protocol¶

Contact:

support@apertodns.com¶

URL:

https://apertodns.com¶

F.1. Version 1.2.3 Changes

• Added ipv4_auto_failed and ipv6_auto_failed error codes to Section 8.3 (Standard Error Codes)¶

• Added "Auto-Detection Limitations" subsection to Section 7.3 (Update Endpoint) documenting HTTP connection semantics constraints¶

• Added validation_error and invalid_ttl error codes¶

• Added example response for auto-detection failure¶

• Updated protocol version in examples from "1.2.0" to "1.3.0"¶

• Added acknowledgment of IETF DNSOP working group¶

F.2. Version 1.3.0 Changes (TXT Records)

• Added TXT record management endpoint (/txt) for ACME DNS-01 challenges¶

• Added txt_records and txt_max_records capability fields¶

• Added TXT-related error codes: txt_not_supported, txt_limit_exceeded, txt_invalid_name, txt_value_too_long¶

• Added "TXT Record Abuse Prevention" section to Security Considerations¶

• Added RFC 8555 (ACME) to normative references¶

• Added TXT Record and ACME DNS-01 terminology definitions¶

• Updated protocol version to 1.3.0¶