KernelHost API

Was die KernelHost API (Reseller API) leistet

Die KernelHost Reseller API bildet exakt jene Bestell- und Verwaltungs-Aktionen ab, die Sie sonst über das Kundenportal klicken würden. Sie automatisieren so Ihr eigenes Hosting-Wiederverkaufs-Geschäft, integrieren KernelHost-Produkte in Ihr eigenes Frontend oder Ihre Abrechnung, und behalten dabei volle Kontrolle über Scopes, Rate-Limits und IP-Whitelist je Schlüssel.

Jeder Aufruf wird mit HMAC-SHA256 signiert, gegen Replay geschützt, idempotent verarbeitet (bei Bestellungen Pflicht) und in einem manipulationssicheren Audit-Log dokumentiert. Zahlungen laufen automatisch zuerst gegen Ihr Guthaben, dann gegen Ihre hinterlegte Karte. Neue Karten lassen sich aus Sicherheitsgründen nur im Kundenportal hinterlegen (3-D Secure 2).

https://www.kernelhost.com/cp/kernelhost_api/v1

Inhaltsverzeichnis

• Schnellstart in 5 Minuten
• Authentifizierung (HMAC-SHA256)
• Endpunkt-Referenz
• Fehler-Codes (RFC 7807)
• SDKs und Code-Beispiele
• Sicherheit & Best Practices
• Changelog

Was Sie mit der API tun können

• Produkte und Preise abrufen (KVM-Rootserver, Dedicated, Webspace, Minecraft, VPN, Unlimited Traffic).
• Bestellungen aufgeben (mit Idempotency-Key-Schutz gegen Doppel-Buchungen bei Netzwerk-Retries).
• Eigene Services auflisten, Status prüfen und Aktionen ausführen: Start, Stop, Reboot, Kündigung zum Laufzeitende und Rücknahme der Kündigung.
• Service-Zugangsdaten ausschließlich der eigenen Services auslesen (separater Scope, Audit-Log, optionale Bestätigungs-Mail bei jedem Zugriff).
• Rechnungen abrufen, Guthaben prüfen, Rechnungs-PDFs herunterladen.
• Pro Schlüssel eine Webhook-URL hinterlegen. Die Zustellung von Ereignissen (Bestellung, Service, Rechnung) ist in Vorbereitung; bis dahin fragen Sie den Status über GET /v1/orders/{id} und GET /v1/services/{id} ab.

Sicherheit auf höchstem Niveau

Die API wurde mit der Annahme entworfen, dass jeder einzelne Aufruf direkten finanziellen Einfluss hat und Zugriff auf sensible Server-Credentials gewährt. Entsprechend liegen die Sicherheits-Anforderungen über dem üblichen REST-Standard.

• HMAC-SHA256 Request-Signatur über Methode, Pfad, Timestamp, Nonce und Body-Hash. Konstant-Zeit-Vergleich.
• Replay-Schutz: Timestamp-Fenster +-300s, einmaliger Nonce-Cache für 600s.
• Secrets werden serverseitig ausschließlich AES-256-GCM-verschlüsselt persistiert. Klartext nur transient im Speicher zur Signatur-Verifikation. Master-Key liegt außerhalb der Datenbank.
• Granulare Scopes pro Schlüssel: gefährliche Scopes (read:credentials, write:orders) müssen ausdrücklich aktiviert werden, Standard ist read-only.
• Daten-Isolation auf Datenbank-Ebene: jede Abfrage filtert hart auf Ihre Account-ID, Cross-Tenant-Zugriff ist nicht möglich.

Beispiel: eigene Account-Info abfragen

Der Aufruf signiert die gesamte Anfrage mit Ihrem Secret. Das Secret verlässt nie den Client-Speicher; übertragen wird nur die Signatur.

TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $2}')
SIG_INPUT=$(printf 'GET\n/v1/me\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $2}')

curl https://www.kernelhost.com/cp/kernelhost_api/v1/me \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG"

Häufige Fragen

Wer darf die Reseller API nutzen?

Jeder bestehende KernelHost-Kunde kann im Kundenportal über den Menüpunkt "KernelHost API" Schlüssel mit eigenem Label, eigenen Scopes und eigener IP-Whitelist erstellen. Anlegen, rotieren und widerrufen darf nur der Kontoinhaber. Eine separate Reseller-Vereinbarung ist nicht nötig: Alle öffentlich gelisteten Produkte sind über die API bestellbar.

Wie wird bei einer Bestellung bezahlt?

Reihenfolge: zuerst Ihr Guthaben, dann Ihre hinterlegte Zahlungsmethode. Wird die Zahlung abgelehnt oder ist keine Karte hinterlegt, liefert die API HTTP 402 "Payment Required" mit eindeutigem Grund (insufficient_credit_and_no_card, card_declined, credit_apply_failed) und storniert die Bestellung sofort, es bleibt also keine unbezahlte Bestellung zurück.

Kann ich Service-Passwörter über die API auslesen?

Ja, ausschließlich für Ihre eigenen Services und ausschließlich mit dem Scope read:credentials, der bei der Schlüsselerstellung extra aktiviert werden muss. Die Antwort enthält Hostname, IP-Adressen, Benutzername und Passwort. Jeder Zugriff erzeugt einen Audit-Log-Eintrag credentials.read und eine Bestätigungs-Mail an die Account-Adresse, verdeckter Missbrauch fällt also auf.

Was passiert wenn mein Secret kompromittiert wird?

Sie rotieren das Secret mit einem Klick im Kundenportal, das alte Secret ist sofort ungültig. Fehlgeschlagene Anmeldeversuche werden protokolliert und pro Quell-IP gebremst, sperren Ihren Key aber nie. So kann niemand Ihre Integration blockieren, nur weil er Ihre öffentliche Key-ID kennt.