DNS-API: Domains und Kontakte

Diese Seite beschreibt die Endpunkte für Domains und Kontakte (Handles). Grundlagen wie Basis-URL, Authentifizierung und Fehlerformat findest du im API-Überblick. Domain-Endpunkte erfordern einen Token mit Zugriff auf den Bereich Domains, Kontakt-Endpunkte Zugriff auf den Bereich Kontakte.

Die Beispiele verwenden folgende Variablen:

export XCLOUD_DNS_TOKEN='xcdns_...'
export XCLOUD_DNS_API='https://app.xcloud.eu/api/dns/v1'

Kontakte (Handles)

Kontakte enthalten die Inhaber- und Kontaktdaten, die bei der Registry für eine Domain hinterlegt sind. Eine Domain verweist auf Kontakte in vier Rollen: Inhaber, Admin-Kontakt, technischer Kontakt und Zonenverwalter (siehe Kontakte im Benutzerhandbuch).

Methode	Pfad	Beschreibung
`GET`	`/handles`	Alle Kontakte auflisten
`GET`	`/handles/{id}`	Einen Kontakt anzeigen
`POST`	`/handles`	Einen Kontakt anlegen
`PATCH`	`/handles/{id}`	Einen Kontakt ändern
`DELETE`	`/handles/{id}`	Einen Kontakt löschen

Attribute eines Kontakts

Attribut	Pflicht	Beschreibung
`firstname`	ja	Vorname
`lastname`	ja	Nachname
`company`	nein	Organisation (Firma, Verein oder Behörde)
`street`	ja	Straße und Hausnummer
`pcode`	ja	Postleitzahl
`city`	ja	Ort
`country`	ja	Zweistelliger Ländercode (ISO 3166-1), z. B. `DE`
`phone`	ja	Telefonnummer im Format `+49 421 000000`
`fax`	nein	Faxnummer, gleiches Format wie `phone`
`email`	ja	E-Mail-Adresse

Antworten enthalten zusätzlich:

Attribut	Beschreibung
`id`	ID des Kontakts
`registrar_handle`	Referenz des Kontakts bei der Registry
`in_use`	Ob eine Domain den Kontakt verwendet
`created_at`	Zeitpunkt der Erstellung

Telefon- und Faxnummern müssen das Format +<Ländervorwahl> <Ortsvorwahl> <Rufnummer> haben, getrennt durch einzelne Leerzeichen. Andere Formate lehnt die Registry ab.

Alle Kontakte abrufen:

curl "$XCLOUD_DNS_API/handles" \
  -H "Authorization: Bearer $XCLOUD_DNS_TOKEN"

{
  "data": [
    {
      "id": "3f1e2d4c-5b6a-4789-8a0b-1c2d3e4f5a61",
      "registrar_handle": "MM12345-XCLOUD",
      "firstname": "Max",
      "lastname": "Muster",
      "company": "Example GmbH",
      "street": "Musterstr. 1",
      "pcode": "28217",
      "city": "Bremen",
      "country": "DE",
      "phone": "+49 421 000000",
      "fax": "",
      "email": "domains@example.com",
      "in_use": true,
      "created_at": "2026-09-14T10:12:48+02:00"
    }
  ]
}

Ohne Wert kommen company und fax in Antworten als leerer String.

Kontakt anlegen

POST /handles legt einen Kontakt an und übermittelt ihn an die Registry:

curl -X POST "$XCLOUD_DNS_API/handles" \
  -H "Authorization: Bearer $XCLOUD_DNS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": {
      "firstname": "Max",
      "lastname": "Muster",
      "company": "Example GmbH",
      "street": "Musterstr. 1",
      "pcode": "28217",
      "city": "Bremen",
      "country": "DE",
      "phone": "+49 421 000000",
      "email": "domains@example.com"
    }
  }'

Die Antwort enthält den angelegten Kontakt in data; du kannst ihn sofort einer Domain zuweisen. Lehnt die Registry die Daten ab, schlägt die Anfrage mit 422 fehl.

Kontakt ändern

PATCH /handles/{id} ändert die angegebenen Attribute; Attribute, die du weglässt, bleiben unverändert. Solange eine Domain den Kontakt verwendet (in_use: true), lassen sich firstname, lastname und company nicht ändern; die Anfrage schlägt dann mit 422 fehl. Um den Inhaber einer Domain zu wechseln, legst du einen neuen Kontakt an und weist ihn der Domain zu (siehe Domain ändern).

Kontakt löschen

DELETE /handles/{id} entfernt den Kontakt aus deinem Projekt. Einen Kontakt, den eine Domain noch verwendet, kannst du nicht löschen (422).

Domains

Methode	Pfad	Beschreibung
`GET`	`/domains`	Alle Domains auflisten
`GET`	`/domains/{id}`	Eine Domain anzeigen
`POST`	`/domains/check`	Prüfen, ob eine Domain verfügbar ist
`POST`	`/domains`	Eine Domain registrieren
`POST`	`/domains/transfer`	Domains zu xCloud transferieren
`PATCH`	`/domains/{id}`	Kontakte oder Nameserver ändern
`DELETE`	`/domains/{id}`	Eine Domain kündigen
`POST`	`/domains/{id}/auto_renew`	Auto-Renew einschalten (Kündigung zurücknehmen)
`DELETE`	`/domains/{id}/auto_renew`	Auto-Renew ausschalten (kündigen)
`POST`	`/domains/bulk_auto_renew`	Auto-Renew für mehrere Domains einschalten
`DELETE`	`/domains/bulk_auto_renew`	Auto-Renew für mehrere Domains ausschalten
`POST`	`/domains/bulk_destroy`	Mehrere Domains kündigen
`POST`	`/domains/{id}/transfer_lock`	Den Transfer-Lock setzen
`DELETE`	`/domains/{id}/transfer_lock`	Den Transfer-Lock entfernen
`POST`	`/domains/{id}/auth_code`	Den Auth-Code für einen Wegzug abrufen

Attribute einer Domain

Attribut	Beschreibung
`id`	ID der Domain
`name`	Domainname, z. B. `example.com`
`state`	Zustand der Domain, siehe unten
`state_detail`	Zusätzliche Informationen zum Zustand, z. B. ein Fehler, oder `null`
`order_number`	Auftragsnummer bei der Registry oder `null`
`nameserver_mode`	`zone` oder `custom`, siehe unten
`nameservers`	Die eigenen Nameserver der Domain im Modus `custom`
`zone_id`	ID der verknüpften xCloud-Zone oder `null`
`owner_handle`	Inhaber: Objekt mit `id`, `registrar_handle` und `label`
`admin_handle`	Admin-Kontakt, gleiche Struktur
`tech_handle`	Technischer Kontakt, gleiche Struktur
`zone_handle`	Zonenverwalter, gleiche Struktur
`registered_at`	Zeitpunkt der Registrierung oder `null`
`paid_until`	Ende der bezahlten Laufzeit oder `null`
`auto_renew`	`true`, solange keine Kündigung vorgemerkt ist
`to_be_deleted_date`	Datum, an dem die gekündigte Domain freigegeben wird, oder `null`
`transfer_lock`	Ob der Transfer-Lock gesetzt ist; `null`, solange das unbekannt ist
`lock_synced_at`	Zeitpunkt des letzten Abgleichs des Transfer-Locks oder `null`
`created_at`	Zeitpunkt der Erstellung

Eine Domain abrufen (GET /domains liefert alle Domains in derselben Form):

curl "$XCLOUD_DNS_API/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $XCLOUD_DNS_TOKEN"

{
  "data": {
    "id": "1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f51",
    "name": "example.com",
    "state": "registered",
    "state_detail": null,
    "order_number": "4711",
    "nameserver_mode": "zone",
    "nameservers": [],
    "zone_id": "0b7c4f0e-2a51-4c4e-9a7f-5d3c1e8b9f10",
    "owner_handle": {
      "id": "3f1e2d4c-5b6a-4789-8a0b-1c2d3e4f5a61",
      "registrar_handle": "MM12345-XCLOUD",
      "label": "Example GmbH"
    },
    "admin_handle": {
      "id": "3f1e2d4c-5b6a-4789-8a0b-1c2d3e4f5a61",
      "registrar_handle": "MM12345-XCLOUD",
      "label": "Example GmbH"
    },
    "tech_handle": {
      "id": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e02",
      "registrar_handle": "EM67890-XCLOUD",
      "label": "Erika Mustermann"
    },
    "zone_handle": {
      "id": "3f1e2d4c-5b6a-4789-8a0b-1c2d3e4f5a61",
      "registrar_handle": "MM12345-XCLOUD",
      "label": "Example GmbH"
    },
    "registered_at": "2026-09-14T10:31:22+02:00",
    "paid_until": "2027-09-14",
    "auto_renew": true,
    "to_be_deleted_date": null,
    "transfer_lock": true,
    "lock_synced_at": "2026-10-20T03:30:41+02:00",
    "created_at": "2026-09-14T10:29:05+02:00"
  }
}

label ist der Name der Organisation oder, ohne Organisation, Vor- und Nachname.

Das Attribut state zeigt den Fortschritt von Bestellungen und Änderungen:

Zustand	Bedeutung
`ordering`	Die Registrierung ist bestellt und läuft
`transfer_pending`	Der Transfer zu xCloud läuft
`registered`	Die Domain ist aktiv
`update_pending`	Eine Änderung von Kontakten oder Nameservern läuft
`deleting`	Die Domain wird gelöscht
`deleted`	Die Domain wurde freigegeben
`failed`	Die Registry hat Bestellung oder Änderung abgelehnt, siehe `state_detail`

Nameserver-Modus

Beim Registrieren, Transferieren oder Ändern einer Domain legt nameserver_mode fest, welche Nameserver die Registry für die Domain einträgt:

zone: Die Domain nutzt die Nameserver ihrer xCloud-Zone. Schick beim Registrieren oder Transferieren zusätzlich "create_zone": true mit: xCloud legt dann eine Zone mit dem Domainnamen an oder verknüpft eine bereits vorhandene gleichnamige Zone in deinem Projekt.
custom: Die Domain nutzt deine eigenen Nameserver. Gib in nameservers mindestens zwei Hostnamen an.

Verfügbarkeit prüfen

POST /domains/check prüft, ob sich eine Domain registrieren lässt. Der Name wird ohne äußeres Objekt geschickt:

curl -X POST "$XCLOUD_DNS_API/domains/check" \
  -H "Authorization: Bearer $XCLOUD_DNS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com"}'

Die Antwort enthält name, available (true oder false) und den von der Registry gemeldeten status. Ergebnisse werden kurz zwischengespeichert.

Domain registrieren

POST /domains bestellt eine Domain bei der Registry.

Attribut	Pflicht	Beschreibung
`name`	ja	Domainname
`owner_handle_id`	ja	ID des Inhaber-Kontakts
`admin_handle_id`	nein	ID des Admin-Kontakts; Standard: der Inhaber
`tech_handle_id`	nein	ID des technischen Kontakts; Standard: der Inhaber
`zone_handle_id`	nein	ID des Zonenverwalters; Standard: der Inhaber
`nameserver_mode`	ja	`zone` oder `custom`, siehe oben
`nameservers`	bei `custom`	Mindestens zwei Nameserver-Hostnamen
`create_zone`	nein	`true` legt die xCloud-Zone der Domain an oder verknüpft sie

Eine Domain mit eigener xCloud-Zone und einem separaten technischen Kontakt registrieren:

curl -X POST "$XCLOUD_DNS_API/domains" \
  -H "Authorization: Bearer $XCLOUD_DNS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": {
      "name": "example.com",
      "owner_handle_id": "3f1e2d4c-5b6a-4789-8a0b-1c2d3e4f5a61",
      "tech_handle_id": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e02",
      "nameserver_mode": "zone",
      "create_zone": true
    }
  }'

Die Bestellung läuft im Hintergrund: Die Antwort zeigt die Domain im Zustand ordering. Sobald die Registry die Registrierung bestätigt hat, wechselt der Zustand zu registered; lehnt die Registry sie ab, zu failed. Mit create_zone enthält zone_id bereits die ID der neuen oder verknüpften Zone, in der du sofort Records anlegen kannst.

Domains transferieren

POST /domains/transfer transferiert eine oder mehrere Domains von einem anderen Anbieter zu xCloud. Für jede Domain brauchst du den Auth-Code des bisherigen Anbieters; der Transfer-Lock muss dort entfernt sein. Die Attribute sind dieselben wie bei einer Registrierung, aber statt name schickst du eine Liste transfers mit name und auth_code pro Domain, höchstens 40 Domains pro Anfrage. Kontakte und Nameserver-Einstellungen gelten für alle Domains der Anfrage.

Zwei Domains transferieren, die weiterhin ihre eigenen Nameserver nutzen:

curl -X POST "$XCLOUD_DNS_API/domains/transfer" \
  -H "Authorization: Bearer $XCLOUD_DNS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": {
      "transfers": [
        { "name": "example.com", "auth_code": "Xy7#kL9!pQ2r" },
        { "name": "example.net", "auth_code": "Ab3$dE6&fG8h" }
      ],
      "owner_handle_id": "3f1e2d4c-5b6a-4789-8a0b-1c2d3e4f5a61",
      "nameserver_mode": "custom",
      "nameservers": ["ns1.example.org", "ns2.example.org"]
    }
  }'

Eine Transfer-Anfrage gilt ganz oder gar nicht: Ist eine einzige Domain ungültig, wird kein Transfer gestartet und die Anfrage schlägt mit 422 fehl. Die Fehlermeldungen nennen die betroffene Domain, sodass du die Anfrage korrigieren und als Ganzes erneut schicken kannst. Bei Erfolg listet die Antwort alle Domains im Zustand transfer_pending.

Domain ändern

PATCH /domains/{id} ändert die Kontakte oder Nameserver einer registrierten Domain. Du kannst die Attribute owner_handle_id, admin_handle_id, tech_handle_id, zone_handle_id, nameserver_mode und nameservers schicken; Attribute, die du weglässt, bleiben unverändert. Eine Rolle lässt sich nicht auf „Wie Inhaber“ zurücksetzen; weise stattdessen ausdrücklich die Kontakt-ID des Inhabers zu.

Eine Domain auf eigene Nameserver umstellen:

curl -X PATCH "$XCLOUD_DNS_API/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer $XCLOUD_DNS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": {
      "nameserver_mode": "custom",
      "nameservers": ["ns1.example.org", "ns2.example.org"]
    }
  }'

Die Änderung läuft im Hintergrund (Zustand update_pending). Änderungen sind nur im Zustand registered möglich; sonst schlägt die Anfrage mit 422 fehl. Ein Inhaberwechsel löst je nach TLD einen Owner-Change aus, der erneut bestätigt werden muss.

Domain kündigen und Auto-Renew

Domains verlängern sich automatisch, solange auto_renew true ist. DELETE /domains/{id} kündigt eine Domain zum Ende ihrer bezahlten Laufzeit, genau wie DELETE /domains/{id}/auto_renew. Beide liefern die geänderte Domain in data:

Die Domain bleibt bis paid_until im Zustand registered und nutzbar. to_be_deleted_date zeigt das Datum, an dem sie freigegeben wird, und auto_renew wird false.
POST /domains/{id}/auto_renew nimmt die Kündigung zurück. In den letzten fünf Tagen vor to_be_deleted_date ist das nicht mehr möglich (422).
Eine Domain im Zustand failed (eine abgelehnte Bestellung) wird durch DELETE /domains/{id} sofort gelöscht.

Ist das Laufzeitende noch nicht bekannt (paid_until ist null), wird die Kündigung mit 422 abgelehnt; versuch es später erneut.

Sammelaktionen

Drei Endpunkte wirken auf mehrere Domains gleichzeitig, höchstens 40 pro Anfrage:

POST /domains/bulk_destroy kündigt die Domains (wie DELETE /domains/{id})
DELETE /domains/bulk_auto_renew schaltet Auto-Renew aus
POST /domains/bulk_auto_renew schaltet Auto-Renew wieder ein

Alle drei nehmen denselben Body an:

curl -X POST "$XCLOUD_DNS_API/domains/bulk_destroy" \
  -H "Authorization: Bearer $XCLOUD_DNS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": {
      "ids": [
        "1d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f51",
        "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c92"
      ]
    }
  }'

Zuerst prüft xCloud, ob die Aktion für jede Domain möglich ist. Ist sie auch nur für eine Domain nicht möglich, wird nichts ausgeführt und die Anfrage schlägt mit 422 fehl, wobei die betroffenen Domains aufgeführt werden. Andernfalls wird die Aktion für jede Domain einzeln ausgeführt. Die Antwort enthält die Domains in data und in errors die Domains, für die die Registry die Aktion abgelehnt hat, mit name und message:

{
  "data": [ { "id": "1d2e3f4a-...", "name": "example.com", "...": "..." } ],
  "errors": [ { "name": "example.net", "message": "..." } ]
}

Transfer-Lock

POST /domains/{id}/transfer_lock setzt den Transfer-Lock bei der Registry, DELETE /domains/{id}/transfer_lock entfernt ihn. Solange der Lock gesetzt ist, kann die Domain nicht zu einem anderen Anbieter transferiert werden. Beide Anfragen wirken sofort und sind nur für Domains im Zustand registered möglich.

Auth-Code

POST /domains/{id}/auth_code liefert den Auth-Code, den du für den Transfer der Domain zu einem anderen Anbieter brauchst:

{ "data": { "auth_code": "..." } }

Bei .de-Domains erzeugt jede Anfrage einen neuen Auth-Code. Die Anfrage ist nur für Domains im Zustand registered möglich. Gib den Auth-Code nur an deinen neuen Anbieter weiter und entferne vor dem Transfer den Transfer-Lock.