Snelstart

1. API-sleutel aanmaken

Log in op het klantenportaal onder "KernelHost API" en maak een sleutel aan. Kies alleen de machtigingen die u echt nodig hebt (standaard: alleen-lezen). Het secret wordt maar één keer getoond, dus bewaar het veilig in uw secret-manager.

2. Toegangsgegevens opslaan

Sla sleutel en geheime sleutel op als omgevingsvariabelen, nooit in code, nooit in een repository.

# .env of shell-profiel
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. Eerste aanvraag versturen

Vraag de lijst met beschikbare producten op. De handtekening wordt opgebouwd over methode, pad, tijdstempel, nonce en body-hash.

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. Bestelling plaatsen

Belangrijk: POST /v1/orders vereist een Idempotency-Key en een hostnaam. Herhaalt u de aanvraag na een netwerkfout met dezelfde key, dan krijgt u dezelfde response terug in plaats van een tweede bestelling. Configuratieopties die u weglaat (bijvoorbeeld locatie of besturingssysteem) krijgen de eerste waarde die in de shop wordt aangeboden.

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 controleren en toegangsgegevens uitlezen

De response van de bestelling bevat de service_ids. Roep GET /v1/services/{id} aan totdat status op active staat en er een IP-adres is toegewezen; de inrichting duurt meestal enkele seconden tot een paar minuten. Daarna retourneert GET /v1/services/{id}/credentials (machtiging read:credentials) hostnaam, IP-adressen, gebruikersnaam en wachtwoord, bijvoorbeeld voor uw 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 opslaan (optioneel)

U kunt nu al per sleutel een HTTPS-URL opslaan. Het versturen van events is in voorbereiding; gebruik tot die tijd de statusopvragingen uit stap 5.