Ghid rapid

1. Creați o cheie API

Autentificați-vă în portalul de clienți, secțiunea "KernelHost API" și creați o cheie. Alegeți doar permisiunile de care aveți cu adevărat nevoie (implicit: doar citire). Codul secret este afișat o singură dată; păstrați-l în siguranță, în managerul dumneavoastră de secrete.

2. Stocați credențialele

Salvați cheia API și codul secret ca variabile de mediu. Niciodată în cod, niciodată într-un depozit.

# .env sau profilul de shell
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. Trimiteți prima cerere

Listați produsele disponibile. Semnătura este construită peste metodă, cale, marcaj temporal, nonce și hash al corpului.

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. Plasați o comandă

Important: POST /v1/orders necesită un Idempotency-Key și un hostname. Dacă, după o eroare de rețea, repetați cererea cu același Idempotency-Key, primiți înapoi același răspuns, fără să se creeze o a doua comandă. Opțiunile configurabile pe care le omiteți (de exemplu locația sau sistemul de operare) primesc prima valoare oferită în magazin.

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. Verificați starea și citiți credențialele

Răspunsul la comandă conține service_ids. Interogați GET /v1/services/{id} până când status are valoarea active și serviciului i-a fost atribuită o adresă IP; configurarea durează de obicei între câteva secunde și câteva minute. Apoi, GET /v1/services/{id}/credentials (permisiunea read:credentials) returnează hostname-ul, adresele IP, numele de utilizator și parola, de exemplu pentru inventarul dumneavoastră Ansible.

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. Înregistrați o adresă URL de webhook (opțional)

Încă de pe acum puteți înregistra câte o adresă URL HTTPS pentru fiecare cheie. Trimiterea evenimentelor este în pregătire; până atunci, folosiți interogările de stare de la pasul 5.