API Reseller KernelHost

Cosa offre l'API Reseller

L'API Reseller di KernelHost espone esattamente le azioni di ordine e gestione che altrimenti effettuerebbe tramite il portale clienti. Le consente di automatizzare la sua attività di rivendita, integrare i prodotti KernelHost nel proprio frontend o sistema di fatturazione e mantenere il pieno controllo su permessi, limiti di velocità e liste IP autorizzate per ogni chiave.

Ogni chiamata è firmata con HMAC-SHA256, protetta contro replay, processata in modo idempotente (obbligatorio per gli ordini), registrata in un audit log a prova di manomissione e opzionalmente confermata tramite webhook. I pagamenti vengono addebitati prima sul saldo credito, poi sulla carta memorizzata. Nuove carte possono essere aggiunte solo nel portale clienti (3-D Secure 2 obbligatorio).

https://www.kernelhost.com/cp/kh_reseller_api/v1

Indice dei contenuti

• Avvio rapido in 5 minuti
• Autenticazione (HMAC-SHA256)
• Riferimento endpoint
• Codici di errore (RFC 7807)
• SDK: PHP, Node.js, Python, Go
• Sicurezza e best practice
• Changelog

Cosa può fare con l'API

• Consultare prodotti e prezzi (rootserver KVM, dedicati, webspace, Minecraft, VPN, traffico illimitato).
• Effettuare ordini (Idempotency-Key protegge da doppi addebiti su retry di rete).
• Elencare i propri servizi, verificarne lo stato, eseguire azioni (start, stop, reboot, reinstall, suspend, terminate).
• Leggere le credenziali esclusivamente dei propri servizi (permesso separato, registrato in audit, email di conferma opzionale ad ogni accesso).
• Recuperare fatture, verificare il saldo credito, scaricare i PDF delle fatture.
• Registrare un webhook per ogni chiave per eventi di ordini, servizi e fatture (schema di firma compatibile con Stripe).

Progettazione a massima sicurezza

L'API è progettata partendo dal presupposto che ogni chiamata abbia un impatto finanziario diretto e possa esporre credenziali server sensibili. Il livello di sicurezza è quindi nettamente superiore agli standard REST abituali.

• Firma della richiesta HMAC-SHA256 su metodo, percorso, timestamp, nonce e hash del body. Confronto a tempo costante.
• Protezione replay: finestra timestamp +-300s, cache nonce monouso per 600s.
• I segreti vengono persistiti esclusivamente come ciphertext AES-256-GCM. Il testo in chiaro esiste solo transitoriamente in memoria per la verifica della firma. La master key risiede al di fuori del database.
• Permessi granulari per ogni chiave. I permessi pericolosi (read:credentials, write:orders) devono essere abilitati esplicitamente. Predefinito è sola lettura.
• Isolamento dati a livello database: ogni query filtra rigorosamente sul suo account id. L'accesso cross-tenant è impossibile per progettazione.

Esempio: interrogare il proprio account

La richiesta viene firmata integralmente con il suo segreto. Il segreto non lascia mai la memoria del client, viene trasmessa solo la firma.

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"

Domande frequenti

Chi può utilizzare l'API Reseller?

Ogni cliente KernelHost esistente può creare una chiave in "Il mio account, API Reseller" con etichetta, permessi e lista IP autorizzati personalizzati. Non è necessario alcun accordo reseller separato: tutti i prodotti pubblicamente disponibili sono accessibili tramite l'API.

Come vengono pagati gli ordini?

Ordine: prima saldo credito, poi metodo di pagamento memorizzato (carta di credito con 3-D Secure 2). Se il pagamento viene rifiutato o non è registrata alcuna carta, l'API restituisce HTTP 402 "Payment Required" con motivo specifico (insufficient_credit_and_no_card, card_declined, card_expired). L'ordine resta in "pending payment" per 24h e viene poi annullato automaticamente.

Posso leggere le password dei servizi tramite l'API?

Sì, ma solo per i propri servizi e solo con il permesso esplicito read:credentials, che deve essere abilitato alla creazione della chiave. Ogni accesso genera una voce di audit log credentials.read; su richiesta può inoltre ricevere un'email di conferma all'indirizzo del suo account, in modo che eventuali abusi silenziosi siano impossibili.

Cosa succede se il mio segreto viene compromesso?

Può ruotare il segreto con un singolo clic nel portale clienti. Il vecchio segreto viene invalidato immediatamente, tutte le sessioni in corso revocate. In caso di fallimenti di autenticazione sospetti (5 in 10 minuti) il sistema blocca automaticamente la chiave per 15 minuti e le invia una notifica via email.