KernelHost API

Cosa offre la KernelHost API (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 il replay, elaborata in modo idempotente (obbligatorio per gli ordini) e registrata in un audit log a prova di manomissione. I pagamenti vengono addebitati prima sul suo saldo credito, poi sulla carta memorizzata. Per motivi di sicurezza, le nuove carte possono essere aggiunte solo nel portale clienti (3-D Secure 2).

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

Indice dei contenuti

• Avvio rapido in 5 minuti
• Autenticazione (HMAC-SHA256)
• Riferimento endpoint
• Codici di errore (RFC 7807)
• SDK ed esempi di codice
• 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 ed eseguire azioni: start, stop, reboot, disdetta alla fine del periodo di fatturazione e revoca della disdetta.
• 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 URL webhook per ogni chiave. L'invio degli eventi (ordini, servizi e fatture) è in preparazione; nel frattempo può verificare lo stato tramite GET /v1/orders/{id} e GET /v1/services/{id}.

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/kernelhost_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 chiavi nel portale clienti tramite la voce di menu "KernelHost API", ciascuna con la propria etichetta, i propri permessi e la propria lista IP autorizzati. Solo il titolare dell'account può creare, ruotare o revocare le chiavi. Non è necessario alcun accordo reseller separato: tutti i prodotti elencati pubblicamente sono ordinabili tramite l'API.

Come vengono pagati gli ordini?

L'addebito avviene prima sul suo saldo credito, poi sul metodo di pagamento memorizzato. Se il pagamento non va a buon fine o non è registrata alcuna carta, l'API restituisce HTTP 402 "Payment Required" con un motivo preciso (insufficient_credit_and_no_card, card_declined, credit_apply_failed) e annulla immediatamente l'ordine, così non rimane in sospeso alcun ordine non pagato.

Posso leggere le password dei servizi tramite l'API?

Sì, esclusivamente per i propri servizi e solo con il permesso esplicito read:credentials, che va abilitato separatamente alla creazione della chiave. La risposta contiene hostname, indirizzi IP, nome utente e password. Ogni accesso genera una voce di audit log credentials.read e un'email di conferma all'indirizzo dell'account, così un eventuale abuso nascosto non passa inosservato.

Cosa succede se il mio segreto viene compromesso?

Può ruotare il secret con un solo clic nell'area clienti e il secret precedente diventa subito non valido. I tentativi di autenticazione falliti vengono registrati e limitati per IP di origine, ma non bloccano mai la Sua chiave: nessuno può bloccare la Sua integrazione solo perché conosce l'ID pubblico della chiave.