CDN64-API: Namen, Tunnel und Portmapper per API v2 verwalten

Mit der CDN64-API (Teil der API v2 von IPv64.net) schaltest du Namen in CDN64 ein und aus, setzt Ziel, Zugriffsliste und Portmapper, pausierst Namen und fragst Kontingent, Traffic und Ereignisse ab. Dieselben Endpunkte nutzen auch die Seite ipv64.net/cdn64 und Node64.

Grundlagen: Adresse, Anmeldung, Format

Alle Endpunkte liegen unter der Basis-URL der API v2; die CDN64-Pfade beginnen mit /cdn64o:

https://ipv64.net/api/v2/cdn64o

Authentifizierung mit API-Key

Du meldest dich mit einem API-Key aus Account → API oder dem API-Key deines Kontos an – per Header, nicht als Parameter:

Authorization: Bearer DEIN_API_KEY
X-API-Key: DEIN_API_KEY

Einer der beiden Header genügt. Fehlt der Key, antwortet die API mit 401 und unauthenticated; ist er falsch, abgelaufen oder das Konto nicht aktiv, mit 401 und invalid_token. Mit dem Header X-IPv64-Act-As (Konto-ID oder E-Mail) handelst du für ein Konto, das dir per Account-Freigabe die Verwaltung erlaubt hat.

Anfragen und Antworten

• Anfragen mit Body schickst du als JSON (Content-Type: application/json); form-urlencoded geht auch. Der Body darf höchstens 1 MB groß sein.
• Erfolg: 200 bzw. 201 (angelegt) mit dem Ergebnis unter data, z. B. {"data": {…}}. Löschen antwortet mit 204 ohne Inhalt.
• Fehler: JSON nach RFC 9457 (application/problem+json) mit type, title, status, detail und code, bei Eingabefehlern zusätzlich field. Alle Codes stehen unter Fehlercodes.
• Zeiten sind ISO 8601 mit Zeitzone, z. B. 2026-10-26T14:05:00+01:00.
• {id} eines Namens ist die numerische ID oder der vollständige Name, z. B. /cdn64o/hosts/www.deinedomain.ipv64.net.

Rate-Limit

Die API v2 begrenzt die Anfragen unabhängig vom API-Limit deiner Kontoklasse: je Konto 300 Anfragen auf einmal, danach 10 pro Sekunde; je IP-Adresse 600 auf einmal, danach 20 pro Sekunde. Fehlgeschlagene Anmeldungen sind je IP auf 20 auf einmal und danach 12 pro Minute begrenzt. Jede Antwort trägt RateLimit-Limit und RateLimit-Remaining; darüber kommt 429 mit Retry-After (Sekunden).

Alle Endpunkte

Die OpenAPI-Beschreibung der API v2 (https://ipv64.net/api/v2/openapi.json) und die Seite ipv64.net/api_v2_docs beschreiben die übrigen Bereiche der API v2.

Übersicht abrufen: GET /cdn64o

Liefert in einem Aufruf dein Kontingent, die Edge-Server, deine Tunnel und alle Namen deines Kontos in CDN64. Eine eigene Liste GET /cdn64o/hosts gibt es nicht – die Namen stehen hier unter hosts.

curl "https://ipv64.net/api/v2/cdn64o" -H "Authorization: Bearer DEIN_API_KEY"

{
  "data": {
    "quota": {
      "domains":  {"used": 2, "old_cdn": 0, "limit": 5},
      "mappings": {"used": 1, "old_cdn": 0, "limit": 10},
      "traffic_mb": {"used": 1834.2, "old_cdn": 0, "limit": 102400},
      "bandwidth_mbit": 1000
    },
    "edges": [
      {"name": "…", "host": "…", "port": 7844, "ips": ["2001:db8::7", "192.0.2.7"]}
    ],
    "tunnels": [ … ],
    "hosts": [ … ]
  }
}

Edge-Server eines Namens: GET und PUT /cdn64o/hosts/{id}/servers

Wie viele Edge-Server ein Name nutzt, legt die Kontoklasse fest (Server je Name). GET zeigt die Zuteilung, mit PUT wählen Business (1 oder 2 Server, 1 oder 2 Verbindungen) und Company (1 bis alle Server, 1 bis 4 Verbindungen) für diesen Namen die Anzahl der Server (count) und die Verbindungen je Server (sessions; in Modus 3 ohne Wirkung). Ein fehlendes Feld bleibt. Node64 bietet dafür einen Knopf in der Zeile des Proxy-Hosts (Spalte CDN64). Dieselbe Auswahl steht im Namens-Objekt unter servers.

curl -X PUT "https://ipv64.net/api/v2/cdn64o/hosts/www.deinedomain.ipv64.net/servers" -H "Authorization: Bearer DEIN_API_KEY" \
  -H "Content-Type: application/json" -d '{"count": 3, "sessions": 2}'

{
  "data": {
    "count": 3, "choice": 3, "max": 4, "all": true, "total": 4, "selectable": true,
    "assigned": ["…", "…", "…"],
    "active": ["…", "…", "…"],
    "sessions": 2, "sessions_max": 4
  }
}

Fehler: Klasse ohne Wahl 403 (plan_not_allowed), Anzahl außerhalb der Grenzen 422 (out_of_range), fremder Name 404. Nach einem PUT stellt IPv64.net das DNS des Namens um (Ereignis servers_changed); der Tunnel seiner Node verbindet binnen einer Minute zu den neuen Servern.

GET und PUT /cdn64o/tunnels/{id}/servers (gleiche Felder) gibt es weiter für ältere Node64: Das PUT setzt die Auswahl für alle Namen des Tunnels (und für den Tunnel selbst, solange er keine Namen hat), das GET zeigt die seines ersten Namens.

Namen einschalten, ändern und ausschalten

Namen einschalten: POST /cdn64o/hosts

Vor dem Einschalten prüft IPv64.net: Kontoklasse mit CDN-Domains, freies Kontingent und Traffic, Name in deinem Konto, Name noch nicht in CDN64, Domain nicht im früheren CDN, kein CNAME und kein aktives DNS Failover auf dem Namen, bei Modus 3 mit source=records mindestens eine öffentliche A/AAAA-Adresse. Danach stellt IPv64.net das DNS um (siehe DNS). Scheitert das, wird nichts geändert (502, dns_update_failed). Lässt sich auch das Zurücknehmen nicht schreiben, bleibt der Name angelegt (ebenfalls 502, die ID steht in detail); entferne ihn dann später mit DELETE /cdn64o/hosts/{id}. Antwort: 201 mit dem Namens-Objekt.

curl -X POST "https://ipv64.net/api/v2/cdn64o/hosts" \
  -H "Authorization: Bearer DEIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"fqdn":"www.deinedomain.ipv64.net","mode":3,"source":"fixed","target":"server.example.org","scheme":"https","port":443}'

Ein Name in Modus 1 an einem bestehenden Tunnel:

curl -X POST "https://ipv64.net/api/v2/cdn64o/hosts" \
  -H "Authorization: Bearer DEIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"fqdn":"cloud.deinedomain.ipv64.net","mode":1,"tunnel_id":"tn_DEINE_TUNNEL_ID"}'

Namen abfragen: GET /cdn64o/hosts/{id}

curl "https://ipv64.net/api/v2/cdn64o/hosts/www.deinedomain.ipv64.net" -H "Authorization: Bearer DEIN_API_KEY"

{
  "data": {
    "id": 42, "fqdn": "www.deinedomain.ipv64.net", "mode": 3, "wildcard": false,
    "status": "active", "blocked_reason": null, "paused": false, "paused_at": null, "error": null,
    "tunnels": [], "domain_id": 1234, "edges": [ … ], "servers": { … },
    "traffic_month": {"bytes_in": 1048576, "bytes_out": 52428800, "conns": 310, "requests": 2048, "rejected": 3},
    "created_via": "web", "created_at": "2026-10-20T09:12:00+02:00", "updated_at": "2026-10-20T09:12:01+02:00",
    "target": {"source": "fixed", "target": "server.example.org", "addrs": null, "port": 443, "scheme": "https",
               "verify_tls": false, "prefer_ipv6": true, "frontend": 2, "websockets": true, "cache_mb": 0, "cache_minutes": 10},
    "acl": {"default": "off", "list": []},
    "mappings": [],
    "waf": true, "ja4": "block",
    "protection": {"blocked_list": 120, "blocked_acl": 0, "blocked_flood": 4, "blocked_limit": 2, "blocked_waf": 37,
                   "blocked_ja4": 0, "ja4_hits": 15, "blocked_ips": 61, "conns": 310, "conns_v4": 88}
  }
}

Modus und Tunnel ändern: PATCH /cdn64o/hosts/{id}

Alle Felder sind optional; geändert wird nur, was du mitschickst.

• mode – zwischen 1 und 2 wechseln. Ein Wechsel von oder zu Modus 3 geht nicht (422, mode_change_not_possible); dafür den Namen aus- und neu einschalten.
• tunnels – Liste von Tunnel-IDs deines Kontos, nicht leer. Die Reihenfolge ist die Priorität: Es bedient der erste verbundene Tunnel. Die Liste ersetzt die bisherige Zuordnung.
• paused – true oder false (siehe unten).
• waf, ja4 – Schutz auf den Edge-Servern (siehe unten).

curl -X PATCH "https://ipv64.net/api/v2/cdn64o/hosts/42" \
  -H "Authorization: Bearer DEIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"tunnels":["tn_ERSTE_NODE","tn_ZWEITE_NODE"]}'

Pausieren und fortsetzen

Mit paused: true nehmen die Edge-Server für den Namen nichts mehr an und trennen offene Verbindungen; das DNS bleibt auf den Servern. Mit paused: false geht es weiter. Antwort: das Namens-Objekt.

curl -X PATCH "https://ipv64.net/api/v2/cdn64o/hosts/www.deinedomain.ipv64.net" \
  -H "Authorization: Bearer DEIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"paused":true}'

WAF-Muster und JA4 schalten

waf (true/false) schaltet die WAF-Muster (wirken in Modus 2 und 3). ja4 setzt die Stufe für Angriffs-Werkzeuge: off, count (nur zählen) oder block (alle Modi); andere Werte ergeben 422 (invalid_field). Steht ja4_global in GET /cdn64o/protection auf count, zählen die Server auch bei block nur. Jede Änderung steht in den Ereignissen (waf).

curl -X PATCH "https://ipv64.net/api/v2/cdn64o/hosts/42" \
  -H "Authorization: Bearer DEIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"waf":true,"ja4":"block"}'

Namen ausschalten: DELETE /cdn64o/hosts/{id}

Schaltet den Namen aus: Die Records der Edge-Server werden gelöscht, deine ursprünglichen A/AAAA-Records wieder aktiviert, Ziel, Zugriffsliste, Portmapper und Zertifikat entfernt. Antwort: 204. Lehnt der DNS-Server die Änderung ab, kommt 502 (dns_update_failed) – dann später erneut versuchen.

curl -X DELETE "https://ipv64.net/api/v2/cdn64o/hosts/42" -H "Authorization: Bearer DEIN_API_KEY"

Ziel setzen (Modus 3): PUT /cdn64o/hosts/{id}/target

Nur für Namen in Modus 3 (sonst 409, not_mode_3). Felder, die du weglässt, behalten ihren bisherigen Wert. Dieselben Felder nimmt POST /cdn64o/hosts beim Einschalten an; dort gelten die Standardwerte.

curl -X PUT "https://ipv64.net/api/v2/cdn64o/hosts/42/target" \
  -H "Authorization: Bearer DEIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"source":"records","scheme":"http","port":8080,"frontend":2,"cache_mb":256}'

Antwort: das Namens-Objekt. Die Edge-Server übernehmen das neue Ziel innerhalb weniger Sekunden.

Zugriffsliste: GET und PUT /cdn64o/hosts/{id}/acl

Die Erlauben-/Sperrliste wirkt auf den Edge-Servern, in allen Modi und auch für die Portmapper des Namens (in Modus 1 nach der IP aus dem Verbindungsaufbau). PUT ersetzt die ganze Liste.

curl -X PUT "https://ipv64.net/api/v2/cdn64o/hosts/42/acl" \
  -H "Authorization: Bearer DEIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"default":"deny","list":["192.0.2.0/24","2001:db8:1234::/48"]}'

{"data": {"default": "deny", "list": ["192.0.2.0/24", "2001:db8:1234::/48"]}}

Portmapper: /cdn64o/hosts/{id}/mappings

Ein Portmapper öffnet auf allen Edge-Servern einen Port zwischen 50000 und 62000 und reicht TCP oder UDP weiter: in Modus 3 an den Port deines Ziels, in Modus 1 und 2 durch den Tunnel an einen Stream in Node64 (target_port = Port des Streams in der Node).

Anlegen: POST

Ohne listen_port nimmt IPv64.net den Port, den ein anderer Portmapper des Namens für denselben Ziel-Port schon nutzt, sonst den Ziel-Port selbst, wenn er im Bereich frei ist, sonst einen freien Port. Antwort: 201 mit allen Portmappern des Namens.

curl -X POST "https://ipv64.net/api/v2/cdn64o/hosts/42/mappings" \
  -H "Authorization: Bearer DEIN_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"WireGuard","transport":"udp","target_port":51820}'

{"data": [{"id": 7, "name": "WireGuard", "listen_port": 55349, "transport": "udp", "target_port": 51820}]}

Der Dienst ist danach unter www.deinedomain.ipv64.net:55349 (UDP) erreichbar. Je Name und Transport darf jeder Ziel-Port nur einmal vorkommen (409, mapping_exists).

Abfragen und löschen

curl "https://ipv64.net/api/v2/cdn64o/hosts/42/mappings" -H "Authorization: Bearer DEIN_API_KEY"
curl -X DELETE "https://ipv64.net/api/v2/cdn64o/hosts/42/mappings/7" -H "Authorization: Bearer DEIN_API_KEY"

Löschen antwortet mit 204.

Statistik und Ereignisse

GET /cdn64o/stats

Zahlen der Edge-Server je Name und Tag für alle Namen deines Kontos. Parameter days: 1–400, Standard 30.

curl "https://ipv64.net/api/v2/cdn64o/stats?days=7" -H "Authorization: Bearer DEIN_API_KEY"

{"data": [
  {"host_id": 42, "fqdn": "www.deinedomain.ipv64.net", "day": "2026-10-25",
   "bytes_in": 1048576, "bytes_out": 52428800, "conns": 310, "requests": 2048, "rejected": 3}
]}

rejected zählt Abweisungen durch die Edge-Server, z. B. durch Zugriffsliste oder Sperre. Ausgeschaltete Namen erscheinen hier nicht mehr.

GET /cdn64o/protection

Was die Edge-Server für die Namen deines Kontos abgewehrt haben. Parameter days: 1 (heute), 7 oder 30 (Standard); andere Werte ergeben 422.

curl "https://ipv64.net/api/v2/cdn64o/protection?days=7" -H "Authorization: Bearer DEIN_API_KEY"

{"data": {
  "days": 7, "ja4_global": "block",
  "totals": {"blocked_list": 120, "blocked_acl": 0, "blocked_flood": 4, "blocked_limit": 2, "blocked_waf": 37,
             "blocked_ja4": 0, "ja4_hits": 15, "blocked_ips": 61, "conns": 310, "conns_v4": 88},
  "daily": [{"day": "2026-10-21", "blocked_list": 18, …}, …],
  "hosts": [{"id": 42, "fqdn": "www.deinedomain.ipv64.net", "mode": 2, "blocked_list": 120, …}],
  "ja4_top": [{"ja4": "t13d1516h2_8daaf6152771_02713d6af862", "hits": 15}]
}}

GET /cdn64o/hosts/{id}/events

Die letzten 100 Ereignisse eines Namens, neueste zuerst, je mit time, kind und message. Mögliche Werte von kind:

Tunnel: /cdn64o/tunnels

Ein Tunnel steht für eine Node64-Instanz. Node64 meldet ihn beim Einschalten von CDN64 selbst an; selbst brauchst du diese Endpunkte vor allem, um einen nicht mehr genutzten Tunnel zu entfernen.

• POST /cdn64o/tunnels mit name (bis 100 Zeichen) und node_id (bis 64 Zeichen) legt einen Tunnel an. Die Antwort (201) enthält das Tunnel-Objekt, die Edge-Server und unter token den Tunnel-Token – nur dieses eine Mal. IPv64.net speichert nur einen Hash davon. Höchstens 10 Tunnel je Konto (403, limit_reached); ohne CDN-Domains in der Klasse 403, plan_not_allowed.
• POST /cdn64o/tunnels/{id}/token stellt einen neuen Token aus; der alte ist sofort ungültig.
• DELETE /cdn64o/tunnels/{id} entfernt den Tunnel (204). Namen, die an keinem anderen Tunnel mehr hängen, werden dabei ausgeschaltet – mit DNS zurück, Ziel, Zugriffsliste und Portmapper. Lehnt der DNS-Server das ab, kommt 502 (dns_update_failed); Tunnel und Name bleiben, damit du es später erneut versuchen kannst.

GET und PUT /cdn64o/tunnels/{id}/lists lesen bzw. setzen die Sperrliste (deny) und die Freigabeliste (allow) des Tunnels: IP-Adressen und Netze (IPv4/IPv6, CIDR), je Liste höchstens 1000 (sonst 422, list_too_long). Einträge werden einheitlich gespeichert, IPv4-gemappte Netze als IPv4; Adressen mit Zone ergeben 422. Die Edge-Server weisen Adressen der Sperrliste für alle Namen des Tunnels schon beim Verbindungsaufbau ab, die Freigabeliste geht vor. PUT ersetzt die gesendeten Listen, ein fehlendes Feld bleibt. Node64 hält beide Listen mit den Listen unter PROXY64 → Zugriffslisten gleich.

Das Tunnel-Objekt (auch in GET /cdn64o) enthält id (z. B. tn_…), name, node_id, status, created_at, last_seen (letzte Verbindung zu einem Edge-Server), last_edge, node_version, sessions (Höchstwert der Verbindungen je Server), edges (die Server, zu denen der Tunnel verbindet – die aller seiner Namen –, je Server mit sessions: Höchstwert der Namen dort) und servers (Auswahl seines ersten Namens, siehe Edge-Server eines Namens).

curl -X DELETE "https://ipv64.net/api/v2/cdn64o/tunnels/tn_DEINE_TUNNEL_ID" -H "Authorization: Bearer DEIN_API_KEY"

Limits der Kontoklassen: GET /plans

Öffentlich, ohne API-Key. Liefert je Kontoklasse Name, Preis und unter limits die aktuellen Grenzen, für CDN64: cdn_domains, cdn_traffic_gb, cdn_bandwidth_mbit (fehlt bei unbegrenzt), cdn_mappings, cdn_tunnel_sessions, cdn_edges (Edge-Server je Konto, 0 = alle) und cdn_edges_selectable (Anzahl wählbar).

curl "https://ipv64.net/api/v2/plans"

Die Antwort darf 10 Minuten zwischengespeichert werden. Die Werte erklärt Kontingent und Traffic.

Endpunkte der Edge-Server

Die Pfade unter /cdn64o/edge/ (Konfiguration, Traffic-Meldung, Zertifikate, ACME-TXT) nutzen nur die Edge-Server von IPv64.net mit einem eigenen Server-Geheimnis. Mit einem API-Key antworten sie mit 401.

Fehlercodes

Ein Beispiel für eine Fehlerantwort:

{"type": "https://ipv64.net/api/v2/errors#cname_exists", "title": "Conflict", "status": 409,
 "detail": "The name has a CNAME record. Remove it first.", "code": "cname_exists"}

Was die Meldungen praktisch bedeuten, steht unter CDN64 → Fehlersuche. Die übrigen Bereiche der API beschreibt die Seite API.

Fehler gefunden oder etwas fehlt? Schreibt uns im v64.tech-Forum. · Stand: 2026-11-03