API Reseller: comenzi programatice cu HMAC

Ce face API-ul Reseller

API-ul Reseller KernelHost expune exact acele acțiuni de comandă și administrare pe care altfel le-ați parcurge prin clic în portalul de clienți. Vă permite să automatizați propria activitate de revânzare, să integrați produsele KernelHost în frontendul sau sistemul propriu de facturare și să păstrați control complet asupra permisiunilor, limitelor de rată și listelor albe IP pentru fiecare cheie.

Fiecare apel este semnat cu HMAC-SHA256, protejat împotriva atacurilor de tip replay, procesat idempotent (obligatoriu pentru comenzi), înregistrat într-un jurnal de audit rezistent la manipulări și, opțional, confirmat prin webhook. Plățile se efectuează mai întâi din soldul de credit, apoi de pe cardul salvat. Cardurile noi pot fi adăugate exclusiv în portalul de clienți (cu 3-D Secure 2 obligatoriu).

URL de bază

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

Cuprins

Ce puteți face

Consultați produse și prețuri (rootservere KVM, servere dedicate, webspace, Minecraft, VPN, trafic nelimitat).
Plasați comenzi (Idempotency-Key protejează împotriva dublelor debitări la reîncercări de rețea).
Listați propriile servicii, verificați starea, executați acțiuni (start, stop, repornire, reinstalare, suspendare, reziliere).
Citiți credențialele exclusiv ale propriilor servicii (permisiune separată, înregistrată în audit, e-mail opțional de confirmare la fiecare acces).
Obțineți facturi, verificați soldul de credit, descărcați PDF-urile facturilor.
Înregistrați un webhook per cheie pentru evenimente de comenzi, servicii și facturi (schemă de semnătură compatibilă Stripe).

Concept de securitate la nivel maxim

API-ul este proiectat pornind de la premisa că fiecare apel are impact financiar direct și poate expune credențiale sensibile de server. Cerințele de securitate sunt, prin urmare, mult peste standardele uzuale REST.

Semnătură HMAC-SHA256 a cererii peste metodă, cale, marcaj temporal, nonce și hash al corpului. Comparație în timp constant.
Protecție împotriva atacurilor replay: fereastră de marcaj temporal +-300s, cache de nonce de unică folosință timp de 600s.
Codurile secrete sunt stocate exclusiv sub formă de criptograme AES-256-GCM. Forma în clar există tranzitoriu doar în memorie, pentru verificarea semnăturii. Cheia master se află în afara bazei de date.
Permisiuni granulare pentru fiecare cheie. Permisiunile periculoase (read:credentials, write:orders) trebuie activate explicit. Valoarea implicită este doar pentru citire.
Izolarea datelor la nivel de bază de date: fiecare interogare filtrează strict după ID-ul contului dumneavoastră. Accesul între tenanți este imposibil prin construcție.

Exemplu: interogarea propriului cont

Cererea este semnată integral cu codul secret. Codul secret nu părăsește niciodată memoria clientului; doar semnătura este transmisă.

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"

Întrebări frecvente

Cine poate utiliza API-ul Reseller?

Orice client existent KernelHost poate crea o cheie din "Contul meu → API Reseller", cu propria etichetă, permisiuni și listă albă IP. Nu este necesar un contract separat de reseller: fiecare produs listat public este disponibil prin API.

Cum sunt plătite comenzile?

Ordine de debitare: mai întâi soldul de credit, apoi metoda de plată salvată (card de credit cu 3-D Secure 2). Dacă plata este refuzată sau nu există card înregistrat, API-ul returnează HTTP 402 "Payment Required" cu un motiv specific (insufficient_credit_and_no_card, card_declined, card_expired). Comanda rămâne în starea "pending payment" timp de 24h și apoi este anulată automat.

Pot citi parolele serviciilor prin API?

Da, însă doar pentru propriile servicii și doar cu permisiunea explicită read:credentials, care trebuie activată la crearea cheii. Fiecare acces generează o intrare în jurnalul de audit credentials.read; la cerere, primiți suplimentar un e-mail de confirmare la adresa contului, astfel încât abuzul tăcut să fie imposibil.

Ce se întâmplă dacă codul meu secret este compromis?

Rotiți codul secret cu un singur clic în portalul de clienți. Vechiul cod secret este invalidat imediat, iar toate sesiunile active sunt revocate. La eșecuri suspecte de autentificare (5 în 10 minute), sistemul blochează automat cheia timp de 15 minute și vă notifică prin e-mail.

Sunteți pregătit să începeți?

Creați prima cheie API în portalul de clienți, secțiunea "API Reseller" și urmați ghidul rapid.