KernelHost Reseller API

Co Reseller API umožňuje

KernelHost Reseller API zpřístupňuje přesně ty objednávací a správní akce, které byste jinak prováděli kliknutím v zákaznickém portálu. Umožňuje Vám automatizovat vlastní reselling, integrovat produkty KernelHost do vlastního frontendu nebo fakturace a udržet si plnou kontrolu nad oprávněními, omezením rychlosti a seznamem povolených IP pro každý klíč.

Každé volání je podepsáno HMAC-SHA256, chráněno proti opakování, zpracováno idempotentně (u objednávek povinné), zaznamenáno v auditním logu odolném proti manipulaci a volitelně potvrzeno přes webhook. Platby se nejprve strhávají z Vašeho kreditu, poté z uložené karty. Nové karty lze z bezpečnostních důvodů přidat pouze v zákaznickém portálu (vyžadováno 3-D Secure 2).

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

Obsah

• Rychlý start za 5 minut
• Autentizace (HMAC-SHA256)
• Reference koncových bodů
• Chybové kódy (RFC 7807)
• SDK: PHP, Node.js, Python, Go
• Bezpečnost a osvědčené postupy
• Changelog

Co s API můžete dělat

• Načítat produkty a ceny (KVM rootservery, dedikované, webhosting, Minecraft, VPN, neomezený provoz).
• Zadávat objednávky (Idempotency-Key chrání proti dvojím platbám při opakovaných pokusech v síti).
• Vypisovat vlastní služby, kontrolovat stav, spouštět akce (start, stop, restart, reinstalace, pozastavení, ukončení).
• Číst přístupové údaje výhradně vlastních služeb (samostatné oprávnění, auditní log, volitelný potvrzovací e-mail při každém přístupu).
• Načítat faktury, kontrolovat zůstatek kreditu, stahovat PDF faktur.
• Registrovat webhook URL pro každý klíč pro události objednávek, služeb a faktur (signaturní schéma kompatibilní se Stripe).

Návrh s maximální bezpečností

API bylo navrženo s předpokladem, že každé jednotlivé volání má přímý finanční dopad a může zpřístupnit citlivé serverové přístupové údaje. Bezpečnostní laťka je proto nastavena výrazně nad obvyklý REST standard.

• HMAC-SHA256 podpis požadavku přes metodu, cestu, časové razítko, nonce a hash těla. Porovnání v konstantním čase.
• Ochrana proti opakování: časové okno +-300 s, jednorázová cache nonce po dobu 600 s.
• Tajné klíče jsou uloženy výhradně jako šifrovaný text AES-256-GCM. Otevřený text existuje pouze přechodně v paměti pro ověření podpisu. Hlavní klíč leží mimo databázi.
• Granulární oprávnění pro každý klíč. Nebezpečná oprávnění (read:credentials, write:orders) musí být výslovně povolena, výchozí stav je pouze pro čtení.
• Izolace dat na úrovni databáze: každý dotaz tvrdě filtruje podle Vašeho ID účtu. Přístup napříč nájemníky je už principiálně nemožný.

Příklad: dotaz na vlastní účet

Celý požadavek je podepsán Vaším tajným klíčem. Tajný klíč nikdy neopouští paměť klienta, přenáší se pouze podpis.

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"

Často kladené otázky

Kdo může Reseller API používat?

Každý stávající zákazník KernelHost si může v sekci "Můj účet → Reseller API" vytvořit klíč s vlastním označením, oprávněními a seznamem povolených IP. Samostatná reselleru smlouva není vyžadována: všechny veřejně nabízené produkty jsou objednatelné přes API.

Jak probíhá platba u objednávky?

Pořadí: nejprve Váš kredit (zůstatek), poté uložená platební metoda (kreditní karta s 3-D Secure 2). Pokud je platba zamítnuta nebo není uložena žádná karta, API vrátí HTTP 402 "Payment Required" s konkrétním důvodem (insufficient_credit_and_no_card, card_declined, card_expired). Objednávka zůstává 24 hodin ve stavu "pending payment", poté je automaticky stornována.

Mohu číst hesla služeb přes API?

Ano, ale pouze pro vlastní služby a pouze s výslovným oprávněním read:credentials, které musí být povoleno při vytváření klíče. Každý přístup vytvoří záznam v auditním logu credentials.read; na přání můžete navíc dostávat potvrzovací e-mail na adresu Vašeho účtu, aby tichá zneužití nebyla možná.

Co se stane, pokud je můj tajný klíč kompromitován?

Tajný klíč můžete kdykoliv obnovit jediným kliknutím v zákaznickém portálu. Starý tajný klíč je okamžitě neplatný, všechny běžící relace jsou ukončeny. Při podezřelých chybách autentizace (5 v 10 minutách) systém klíč automaticky uzamkne na 15 minut a informuje Vás e-mailem.