Schnellstart

1. API-Key erstellen

Loggen Sie sich im Kundenportal unter "KernelHost API" ein und erstellen Sie einen Key. Wählen Sie nur die Scopes, die Sie tatsächlich brauchen (Standard: lesend). Das Secret wird nur einmal angezeigt, speichern Sie es sicher in Ihrem Secret-Manager.

2. Credentials hinterlegen

Speichern Sie Key und Secret als Umgebungsvariablen, niemals im Code, niemals im Repository.

# .env oder Shell-Profil
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. Erste Anfrage senden

Liste der verfügbaren Produkte abrufen. Die Signatur wird über Methode, Pfad, Timestamp, Nonce und Body-Hash gebildet.

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

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

4. Bestellung aufgeben

Wichtig: POST /v1/orders erfordert einen Idempotency-Key und einen Hostnamen. Wiederholen Sie die Anfrage nach einem Netzwerkfehler mit demselben Key, bekommen Sie dieselbe Antwort zurück statt einer zweiten Bestellung. Nicht angegebene Konfigurationsoptionen (etwa Standort oder Betriebssystem) erhalten den ersten im Shop angebotenen Wert.

BODY='{"product_id":42,"billing_cycle":"monthly","hostname":"web01.example.com"}'
IDEM="order-web01-$(date +%Y%m%d)"
BODY_SHA256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')
TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
SIG_INPUT=$(printf 'POST\n/v1/orders\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')

curl -X POST https://www.kernelhost.com/cp/kernelhost_api/v1/orders \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG" \
  -H "Idempotency-Key: $IDEM" \
  -H "Content-Type: application/json" \
  --data "$BODY"

5. Status prüfen und Zugangsdaten abrufen

Die Antwort der Bestellung nennt die service_ids. Fragen Sie GET /v1/services/{id} ab, bis status active ist und eine IP-Adresse gesetzt ist; die Einrichtung dauert meist wenige Sekunden bis wenige Minuten. Danach liefert GET /v1/services/{id}/credentials (Scope read:credentials) Hostname, IP-Adressen, Benutzername und Passwort, zum Beispiel für Ihr Ansible-Inventory.

kh_get() {
  TS=$(date +%s)
  NONCE=$(openssl rand -hex 16)
  BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
  SIG_INPUT=$(printf 'GET\n%s\n%s\n%s\n%s' "$1" "$TS" "$NONCE" "$BODY_SHA256")
  SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $NF}')
  curl -s "https://www.kernelhost.com/cp/kernelhost_api$1" \
    -H "KH-Key: $KH_KEY" \
    -H "KH-Timestamp: $TS" \
    -H "KH-Nonce: $NONCE" \
    -H "KH-Signature: $SIG"
}

kh_get /v1/services/1234
kh_get /v1/services/1234/credentials

6. Webhook-URL hinterlegen (optional)

Eine HTTPS-URL pro Key können Sie schon jetzt hinterlegen. Die Zustellung von Ereignissen ist in Vorbereitung; bis dahin nutzen Sie die Statusabfragen aus Schritt 5.