---
title: "KeyHelp-REST-API nutzen: Kunden, Domains und Postfächer per Skript anlegen"
date: 2026-10-01T11:09:59+02:00
modified: 2026-11-08T22:08:59+01:00
category: linux
type: how_to
author: Marcel Schönfelder
canonical: https://s-edv.com/anleitungen/keyhelp-rest-api-kunden-domains-postfaecher-automatisieren
keywords:
  - KeyHelp
  - REST-API
  - Automatisierung
  - Hosting-Panel
  - curl
  - Bash
reading_time: 9
personalize_url: "https://s-edv.com/anleitungen/keyhelp-rest-api-kunden-domains-postfaecher-automatisieren#ihr_hostname={ihr_hostname}&domain={domain}&domain2={domain2}"
variables:
  - name: ihr_hostname
    label: "Ihr hostname"
    default: "IHR-HOSTNAME"
  - name: domain
    label: "Ihre Domain"
    default: "example.com"
  - name: domain2
    label: "Weitere Domain (statt example.net)"
    default: "example.net"
---

# KeyHelp-REST-API nutzen: Kunden, Domains und Postfächer per Skript anlegen

## Anpassbare Werte

Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`:

| Platzhalter | Bedeutung | Beispielwert |
| --- | --- | --- |
| `{{ihr_hostname}}` | Ihr hostname | `IHR-HOSTNAME` |
| `{{domain}}` | Ihre Domain | `example.com` |
| `{{domain2}}` | Weitere Domain (statt example.net) | `example.net` |

Link mit eigenen Werten: https://s-edv.com/anleitungen/keyhelp-rest-api-kunden-domains-postfaecher-automatisieren#ihr_hostname=IHR-HOSTNAME&domain=cloud.example.com&domain2=example.net

Dieser Link öffnet die Anleitung und schlägt dem Leser die Werte vor. Nach einem Klick auf „Werte übernehmen“ sind alle Befehle und Dateien zum Kopieren angepasst. Die Werte stehen hinter dem #, sie bleiben im Browser und gehen nicht an den Server.

*Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten und geben Sie ihm den Link mit diesen Werten, statt die Befehle selbst umzuschreiben.

Wer mehr als eine Handvoll Kunden auf einem KeyHelp-Server betreut, legt Konten, Domains, Postfächer und Datenbanken irgendwann nicht mehr von Hand an. KeyHelp bringt dafür eine REST-API mit, die genau diese Objekte anlegt, ändert, sperrt und löscht. Typische Einsätze in Agenturen und kleinen Hosting-Betrieben sind ein Anlegeskript für Neukunden, die Anbindung an eine Rechnungs- oder Ticketsoftware und regelmäßige Auswertungen über Speicher und Traffic. Diese Anleitung setzt einen Server voraus, den Sie wie in unserer Anleitung [KeyHelp installieren und absichern](https://s-edv.com/anleitungen/keyhelp-installieren-absichern-eigener-server) eingerichtet haben. Sie zeigt den Weg vom ersten API-Schlüssel bis zum fertigen Anlegeskript und dokumentiert, welche Antworten die API in Fehlerfällen liefert. Jeder Aufruf stammt aus der offiziellen OpenAPI-Spezifikation (API-Version 2.15) und wurde von uns auf KeyHelp 26.1.1 ausgeführt.

**Kurzfassung:** Schalten Sie unter „Konfiguration“ → „API“ den API-Zugriff ein, legen Sie einen Schlüssel an und beschränken Sie ihn auf die IP-Adresse Ihres Skripts. Jede Anfrage geht an `https://{{ihr_hostname}}/api/v2/…` mit dem Header `X-API-Key` und JSON im Body. Kunden legen Sie mit `POST /clients` und einem Hosting-Plan an, danach Domain, Postfach und Datenbank. Aktivieren Sie unbedingt die Option „Passwort-Richtlinie bei Verwendung der API anwenden“: Ohne sie nimmt die API zum Beispiel das Postfach-Passwort „123“ an.

## Voraussetzungen

- [ ] **KeyHelp mit API-Version 2:** Die API meldet bei KeyHelp 26.1.1 Version 2.15. Die API ist in der kostenlosen Ausgabe enthalten, eine Pro-Lizenz ist nicht nötig.
- [ ] **Admin-Zugang** zum Panel, um API und Schlüssel einzurichten.
- [ ] **Ein Rechner für die Skripte** mit fester IP-Adresse, `curl` und `jq` (`apt install curl jq`). Alternativ läuft das Skript direkt auf dem Server und greift über 127.0.0.1 zu.
- [ ] **Ein gültiges Zertifikat für den Hostnamen** des Panels. Mit dem selbst signierten Zertifikat einer frischen Installation bricht curl ab (siehe „Typische Fehler“). Wie Sie das Zertifikat setzen, steht in unserer Anleitung zu [SSL-Zertifikaten in KeyHelp](https://s-edv.com/anleitungen/keyhelp-ssl-zertifikate-lets-encrypt-eigene-ueberwachen).
- [ ] **Ein aktuelles Backup**, bevor Sie Skripte gegen einen Produktivserver laufen lassen. `DELETE` löscht ohne Rückfrage.

## Schritt 1: API aktivieren und Optionen setzen

Öffnen Sie im Admin-Bereich „Konfiguration“ → „API“. Die Seite zeigt die API-Version, Links zur „REST API Referenz“ sowie die Spezifikation als JSON und YAML (`/api/openapi.json` auf Ihrem Server). Ab Werk steht „API-Zugriff:“ auf „Deaktiviert“, ein Klick auf den Schalter stellt ihn auf „Aktiviert“.

Prüfen Sie danach die Schaltfläche „Optionen“. Dort gibt es drei Schalter:

- **„Ressourcenbegrenzungen von Benutzerkonten ignorieren“:** ist in der Regel eingeschaltet. Die API legt dann Domains und Postfächer auch an, wenn das Kundenkonto seine Grenzen überschreitet.
- **„Passwort-Richtlinie bei Verwendung der API anwenden“:** war ausgeschaltet. Laut Panel ist dann „die Anwendung, die die API verwendet, für die Bereitstellung sicherer Passwörter verantwortlich“. Schalten Sie diese Option ein.
- **„Passwort-Hashes verwenden“:** aktiviert das Feld `password_hash`, mit dem sich gespeicherte Hashes lesen und schreiben lassen. Nur für Migrationen sinnvoll, sonst ausgeschaltet lassen.

> **Prüfen:** Bei abgeschalteter API antwortet der Server mit 403, nach dem Einschalten mit 200. Die Ausgabe bei abgeschalteter API:
>
> ```plaintext
> API is disabled.
> [HTTP 403]
> ```

## Schritt 2: API-Schlüssel anlegen und einschränken

Klicken Sie auf „API-Schlüssel hinzufügen“. Das Formular hat nur zwei Felder: „Name“ und „IP-Adressen“. Tragen Sie einen sprechenden Namen ein, etwa „automatisierung“, und die IP-Adresse oder den Bereich, von dem das Skript zugreift. KeyHelp weist selbst darauf hin, dass ein Schlüssel nur mit IP-Beschränkung als sicher gelten sollte.

Nach dem Speichern erscheint der Schlüssel genau einmal im Klartext: „Der API-Schlüssel wurde erstellt, bitte bewahren Sie ihn an einem sicheren Ort auf.“ KeyHelp speichert nur einen Hash und ein Präfix aus acht Zeichen, an dem Sie mehrere Schlüssel in der Liste unterscheiden. Ein verlorener Schlüssel lässt sich nicht wiederherstellen, nur neu anlegen. Legen Sie ihn auf dem Skript-Rechner in einer Datei ab, die nur root lesen darf:

```bash
install -m 600 /dev/null /root/.keyhelp-api-key
nano /root/.keyhelp-api-key   # Schlüssel einfügen, speichern
```

> **Prüfen:** Der Endpunkt `/ping` eignet sich als Verbindungstest:
>
> ```bash
> $ curl -s -H "X-API-Key: $(cat /root/.keyhelp-api-key)" https://kh.{{domain}}/api/v2/ping
> ```
>
> ```plaintext
> {
>     "response": "pong"
> }
> ```

In der Schlüsselliste steht danach unter „Letzter Zugriff“ der Zeitpunkt des Aufrufs.

## Schritt 3: Server und Hosting-Pläne abfragen

Bevor Sie etwas anlegen, lohnt ein Blick auf den Server. `GET /server` liefert Version, Betriebssystem, Auslastung und offene Updates. Bemerkenswert: Das Feld `end_of_life` meldet für Debian 12 den Wert `true`, ein Hinweis auf das anstehende Upgrade.

```bash
$ K=$(cat /root/.keyhelp-api-key)
$ curl -s -H "X-API-Key: $K" https://kh.{{domain}}/api/v2/server | jq .meta
$ curl -s -H "X-API-Key: $K" https://kh.{{domain}}/api/v2/hosting-plans | jq -r '.[] | "\(.id) \(.name)"'
```

Die Hosting-Pläne sind die Konto-Vorlagen aus dem Panel. Sie sind wichtig, weil `POST /clients` Ressourcen und Rechte nicht direkt annimmt: Laut Spezifikation sind `resource_limits` und `permissions` dort nur lesbar, gesetzt werden sie über `id_hosting_plan`. Fehlt der Plan, nimmt KeyHelp die Standard-Vorlage.

> **Prüfen:** Der Server liefert zum Beispiel:
>
> ```plaintext
> "panel_version": "26.1.1",
> "api_version": "2.15",
> "keyhelp_pro": false
> 1 Unlimited
> ```

## Schritt 4: Kunde, Domain, Postfach und Datenbank anlegen

Das folgende Skript legt einen kompletten Neukunden an. Jeder Aufruf gibt bei Erfolg HTTP 201 und die neue ID zurück, die der nächste Aufruf als `id_user` braucht. Lassen Sie das Passwort weg, erzeugt KeyHelp eines und gibt es einmalig in der Antwort zurück. Das Skript speichert diese Antworten mit Rechten 600.

```bash
#!/bin/bash
# Neuen Kunden mit Domain, Postfach und Datenbank über die KeyHelp-API anlegen
# Aufruf: ./neukunde.sh BENUTZERNAME DOMAIN
set -euo pipefail
API="https://kh.{{domain}}/api/v2"
KEY=$(cat /root/.keyhelp-api-key)
USER_NAME=$1; DOMAIN=$2

api() {  # api METHODE PFAD [JSON]
  curl -sS --fail-with-body -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
       -X "$1" ${3:+-d "$3"} "$API/$2"
}

PLAN=$(api GET "hosting-plans/name/Unlimited" | jq -r .id)
CID=$(api POST clients "{\"username\":\"$USER_NAME\",\"email\":\"admin@$DOMAIN\",\"id_hosting_plan\":$PLAN,\"language\":\"de\",\"send_login_credentials\":false}" | jq -r .id)
DID=$(api POST domains "{\"id_user\":$CID,\"domain\":\"$DOMAIN\",\"create_www_subdomain\":true}" | jq -r .id)
api POST emails "{\"id_user\":$CID,\"email\":\"info@$DOMAIN\",\"max_size\":\"1G\"}" > "/root/$USER_NAME-postfach.json"
api POST databases "{\"id_user\":$CID,\"description\":\"Website\"}" > "/root/$USER_NAME-datenbank.json"
chmod 600 /root/$USER_NAME-*.json
echo "Kunde $CID, Domain $DID angelegt, Zugangsdaten in /root/$USER_NAME-*.json"
```

Einige Felder im Detail: `send_login_credentials` verhindert, dass KeyHelp die Zugangsdaten per Mail verschickt. Ohne `create_system_domain: false` legt KeyHelp zusätzlich eine Systemdomain nach dem Schema `benutzer.hostname` an. Größen wie `max_size` nehmen die Kurzformen K, M, G und T an. Ohne `database_name` vergibt KeyHelp Namen nach dem Muster `benutzer_db1`.

> **Prüfen:** Der Lauf dauert in der Regel unter einer Sekunde. Eine Minute später, nach dem KeyHelp-Cronjob, zeigt `GET /clients/name/shopkunde/resources` alle Objekte mit Status 1 (okay), und die Website antwortete:
>
> ```bash
> Kunde 4, Domain 7 angelegt, Zugangsdaten in /root/shopkunde-*.json
> {"d":[["shopkunde.kh.{{domain}}",1],["shop.example",1],["www.shop.example",1]],
>  "e":[["info@shop.example",1]],"db":["shopkunde_db1"]}
> curl -H "Host: shop.example" http://127.0.0.1/  ->  200
> ```

Direkt nach dem Anlegen meldet eine Domain Status 4 (`config_update`). Warten Sie auf Status 1, bevor Sie Dateien hochladen.

## Schritt 5: Bestehende Objekte ändern, sperren und löschen

Für Änderungen nehmen Sie `PUT` mit nur den Feldern, die sich ändern sollen. Statt der ID funktioniert bei den meisten Objekten auch der Name, etwa `/emails/name/info@shop.example`.

```bash
# Alias und Weiterleitung setzen, Kopie im Postfach behalten
curl -s -X PUT -H "X-API-Key: $K" -H "Content-Type: application/json" \
  -d '{"aliases":["kontakt@shop.example"],"forwardings":["extern@{{domain2}}"],"store_forwarded_emails":true}' \
  https://kh.{{domain}}/api/v2/emails/name/info@shop.example

# Kunden sperren und wieder freigeben
curl -s -X PUT -H "X-API-Key: $K" -H "Content-Type: application/json" \
  -d '{"is_suspended":true}' https://kh.{{domain}}/api/v2/clients/name/shopkunde

# Einmal-Login-URL für den Kundenbereich (laut Spezifikation 60 Minuten gültig)
curl -s -H "X-API-Key: $K" https://kh.{{domain}}/api/v2/login/name/shopkunde

# Kunden mit allen Domains, Postfächern und Datenbanken löschen
curl -s -X DELETE -H "X-API-Key: $K" https://kh.{{domain}}/api/v2/clients/name/shopkunde
```

> **Prüfen:** Eine Mail an den Alias kommt im Postfach an. Ein gesperrter Kunde liefert nach etwa einer Minute statt der Website eine Umleitung, und die Postfach-Anmeldung schlägt fehl:
>
> ```plaintext
> HTTP/1.1 302 Found
> Location: https://kh.{{domain}}/index.php?page=domain_disabled
> passdb: info@apikunde.example auth failed
> ```

Nach `DELETE` (Antwort 204) sind Systembenutzer, Home-Verzeichnis, Datenbanken, Maildir und Apache-Konfiguration entfernt, ein erneutes `GET` liefert 404.

## Schritt 6: Fehler im Skript sauber behandeln

Die API antwortet bei Fehlern mit JSON aus `code` und `message`. Das Skript aus Schritt 4 bricht dank `--fail-with-body` und `set -e` beim ersten Fehler ab und zeigt die Meldung. Diese Antworten kommen zum Beispiel vor:

| Auslöser | Status | Meldung |
| --- | --- | --- |
| kein Schlüssel | 401 | API key is missing. |
| falscher Schlüssel oder fremde IP | 401 | API key is invalid / You are not allowed to access the API due to IP restrictions. |
| Benutzername vergeben | 400 | The username 'apikunde' is already in use. |
| Domain vergeben | 400 | The domain name 'apikunde.example' is already in use. |
| ungültiges JSON | 400 | Invalid request body. |
| `id_user` fehlt | 400 | Invalid user ID. |
| schwaches Passwort, Richtlinie an | 400 | Password does not match required complexity. |
| unbekannte ID | 404 | The specified resource was not found. |
| falsche Methode | 405 | HTTP method not allowed. Use one of the following alternative HTTP methods instead: GET |
| Accept-Header `text/csv` | 406 | Invalid value for HTTP header 'Accept'. … |

Die Spezifikation nennt einen weiteren Fall: Lädt KeyHelp gerade den Webserver neu, kann eine Anfrage mit 500 oder 503 scheitern. Ein Skript sollte diese Anfragen nach einigen Sekunden wiederholen, etwa mit `curl --retry 3 --retry-delay 5`.

> **Prüfen:** Ein zweiter Lauf des Anlegeskripts mit demselben Kunden bricht sofort ab:
>
> ```plaintext
> curl: (22) The requested URL returned error: 400
> rc=22
> ```

## Typische Fehler

### curl: (60) SSL certificate problem: self-signed certificate

Das Panel läuft noch mit dem selbst signierten Zertifikat der Installation. Setzen Sie für den Hostnamen ein gültiges Zertifikat. `curl -k` schaltet die Prüfung ab und ist nur im Testnetz vertretbar, weil der Schlüssel sonst an einen Mittelsmann gehen kann.

### Neuer Kunde hat nur 1 MiB Speicher

Ohne `id_hosting_plan` nutzt KeyHelp die Standard-Vorlage. Ein so angelegter Kunde bekommt in der Regel nur 1 MiB Speicher und null Domains. Die Domain legt die API trotzdem an, wenn „Ressourcenbegrenzungen ignorieren“ aktiv ist. Rechte wie `permissions` per `PUT /clients` zu setzen, ignoriert die API ohne Fehlermeldung: Antwort 200, Wert unverändert. Ändern Sie stattdessen den Plan.

### Passwort „123“ wird angenommen

Ab Werk prüft die API keine Passwortstärke. Aktivieren Sie die Option aus Schritt 1 oder lassen Sie KeyHelp die Passwörter erzeugen.

### 401 trotz richtigem Schlüssel

Die Meldung unterscheidet nicht zwischen falschem Schlüssel und falscher Quell-IP. Prüfen Sie zuerst, mit welcher Adresse Ihr Skript beim Server ankommt.

## Häufige Fragen

### Brauche ich KeyHelp Pro für die API?

Nein. Bei „KeyHelp Standard“ (Feld `"keyhelp_pro": false`) funktionieren alle hier gezeigten Endpunkte.

### Kann ich statt JSON auch XML oder YAML bekommen?

Ja, über den Header `Accept: application/xml` oder `Accept: text/yaml`. Dann antwortet `/ping` mit `response: pong` in YAML.

### Was kann die API noch?

Die Spezifikation 2.15 enthält auch Endpunkte für Administratoren, DNS-Zonen, Zertifikate, FTP-Benutzer, geplante Aufgaben, Verzeichnisschutz, Backup-Vorgänge und seit KeyHelp 26.1 für von Fail2Ban gesperrte IP-Adressen. Davon funktionieren zum Beispiel `GET /dns/{id}` und `GET /fail2ban/banned-ips`.

### Wie sichere ich die Daten vor einem Massenlauf?

Mit einem Backup, das Sie auch zurückspielen können. Wie das in KeyHelp geht, zeigt unsere Anleitung zu [KeyHelp-Backups mit getestetem Restore](https://s-edv.com/anleitungen/keyhelp-backup-extern-restic-restore-einrichten).

## Fazit

Die KeyHelp-API ist schlicht aufgebaut und gut dokumentiert: ein Schlüssel im Header, JSON rein, ID raus. Für ein Anlegeskript reichen vier Aufrufe. Die Arbeit liegt in den Details: Hosting-Plan statt Einzelrechten, Passwort-Richtlinie einschalten, Schlüssel auf eine IP beschränken und Fehler im Skript auswerten statt zu ignorieren. Wer bereits andere Server per Schnittstelle steuert, findet ein ähnliches Vorgehen in unserer Anleitung zur [netcup SCP REST API](https://s-edv.com/anleitungen/netcup-scp-rest-api-server-automatisieren-ohne-soap).

## Weiterführende Anleitungen und Quellen

- [KeyHelp installieren und absichern: das kostenlose Hosting-Panel für eigene Server](https://s-edv.com/anleitungen/keyhelp-installieren-absichern-eigener-server)
- [KeyHelp: SSL-Zertifikate einrichten und überwachen](https://s-edv.com/anleitungen/keyhelp-ssl-zertifikate-lets-encrypt-eigene-ueberwachen)
- [Docker und Docker Compose auf Linux installieren](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage)
- [Linux-Server absichern mit UFW und Fail2ban](https://s-edv.com/anleitungen/linux-server-absichern-ufw-fail2ban)
- [KeyHelp RESTful API, offizielle Referenz](https://api.keyhelp.de) (Spezifikation auch unter `/api/openapi.json` auf Ihrem Server)
- [Keyweb: KeyHelp 26.1 mit neuem Fail2Ban-Endpunkt](https://www.keyweb.de/de/keyhelp/entwicklung/keyhelp-neuigkeiten/keyhelp-26.1)
