KernelHost Reseller API

Was die 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), in einem manipulationssicheren Audit-Log dokumentiert und auf Wunsch via Webhook bestätigt. 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/kh_reseller_api/v1

Inhaltsverzeichnis

• Schnellstart in 5 Minuten
• Authentifizierung (HMAC-SHA256)
• Endpunkt-Referenz
• Fehler-Codes (RFC 7807)
• SDKs: PHP, Node.js, Python, Go
• 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, Aktionen ausführen (Start, Stop, Reboot, Reinstall, Suspend, Terminate).
• 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.
• Webhook-URL pro Schlüssel hinterlegen für Order-, Service- und Rechnungs-Events (Stripe-kompatibles Signatur-Schema).

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/kh_reseller_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 unter "Mein Account → Reseller API" einen Schlüssel mit eigenem Label, Scopes und IP-Whitelist erstellen. 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 (Credit-Balance), dann Ihre hinterlegte Zahlungsmethode (Kreditkarte mit 3-D Secure 2). Wird die Zahlung abgelehnt oder fehlt eine hinterlegte Karte, liefert die API HTTP 402 "Payment Required" mit eindeutigem Grund (insufficient_credit_and_no_card, card_declined, card_expired) zurück. Die Bestellung bleibt 24h im Status "pending payment", danach wird sie automatisch storniert.

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

Ja, ausschließlich für Ihre eigenen Services und ausschließlich mit dem expliziten Scope read:credentials, der bei Schlüsselerstellung extra aktiviert werden muss. Jeder Zugriff erzeugt einen Audit-Log-Eintrag credentials.read; auf Wunsch erhalten Sie zusätzlich eine Bestätigungs-Mail an die hinterlegte Account-Adresse, damit verdeckter Missbrauch ausgeschlossen ist.

Was passiert wenn mein Secret kompromittiert wird?

Sie rotieren das Secret jederzeit mit einem Klick im Kundenportal. Das alte Secret ist sofort ungültig, alle laufenden Sessions werden invalidiert. Bei verdächtigen Fehl-Authentifizierungen (5 in 10 Minuten) sperrt das System den Schlüssel automatisch für 15 Minuten und informiert Sie per E-Mail.