Avvio rapido

1. Creare una chiave API

Acceda alla sezione "KernelHost API" del portale clienti e crei una chiave. Scelga solo i permessi di cui ha effettivamente bisogno (predefinito: sola lettura). Il segreto viene mostrato una sola volta: lo conservi in modo sicuro nel suo gestore di segreti.

2. Memorizzare le credenziali

Salvi chiave e segreto come variabili d'ambiente. Mai nel codice, mai in un repository.

# .env o profilo shell
export KH_KEY="kh_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
export KH_SECRET="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. Inviare la prima richiesta

Elenchi i prodotti disponibili. La firma viene costruita su metodo, percorso, timestamp, nonce e hash del body.

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. Effettuare un ordine

Importante: POST /v1/orders richiede una Idempotency-Key e un hostname. Se dopo un errore di rete ripete la richiesta con la stessa chiave, riceve la stessa risposta e non viene creato un secondo ordine. Le opzioni configurabili non specificate (ad esempio la sede o il sistema operativo) ricevono il primo valore offerto nello shop.

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. Verificare lo stato e leggere le credenziali

La risposta dell'ordine riporta i service_ids. Interroghi GET /v1/services/{id} finché status non è active e non è stato assegnato un indirizzo IP; l'attivazione richiede di solito da pochi secondi a qualche minuto. A quel punto GET /v1/services/{id}/credentials (permesso read:credentials) restituisce hostname, indirizzi IP, nome utente e password, ad esempio per il suo inventario 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. Registrare un URL webhook (opzionale)

Fin d'ora può registrare un URL HTTPS per ogni chiave. L'invio degli eventi è in preparazione; nel frattempo utilizzi le verifiche di stato descritte al passaggio 5.