KernelHost API

Co KernelHost API (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ě) a zaznamenáno v auditním logu odolném proti manipulaci. Platby se nejprve strhávají z Vašeho kreditu, poté z Vaší uložené karty. Nové karty lze z bezpečnostních důvodů přidat pouze v zákaznickém portálu (3-D Secure 2).

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

Obsah

• Rychlý start za 5 minut
• Autentizace (HMAC-SHA256)
• Reference koncových bodů
• Chybové kódy (RFC 7807)
• SDK a příklady kódu
• 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 jejich stav a spouštět akce: start, stop, reboot, zrušení ke konci fakturačního období a odvolání tohoto zruš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.
• Uložit webhook URL pro každý klíč. Doručování událostí k objednávkám, službám a fakturám je v přípravě; do té doby zjišťujte stav pomocí GET /v1/orders/{id} a GET /v1/services/{id}.

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/kernelhost_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 zákaznickém portálu přes položku menu "KernelHost API" vytvořit klíče a každému z nich přiřadit vlastní označení, oprávnění a seznam povolených IP. Klíče může vytvářet, rotovat a odvolávat pouze vlastník účtu. Samostatná resellerská smlouva není potřeba: všechny veřejně nabízené produkty lze objednat přes API.

Jak probíhá platba u objednávky?

Pořadí úhrady: nejprve z Vašeho kreditu, poté z Vaší uložené platební metody. Pokud platba selže nebo není uložena žádná karta, API vrátí HTTP 402 "Payment Required" s přesným důvodem (insufficient_credit_and_no_card, card_declined, credit_apply_failed) a objednávku okamžitě stornuje, takže nezůstane viset žádná nezaplacená objednávka.

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

Ano, ale pouze pro Vaše vlastní služby a pouze s výslovným oprávněním read:credentials, které je nutné při vytváření klíče zvlášť povolit. Odpověď obsahuje hostname, IP adresy, uživatelské jméno a heslo. Při každém přístupu vznikne v auditním logu záznam credentials.read a na adresu účtu odejde potvrzovací e-mail, takže skryté zneužití nezůstane bez povšimnutí.

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

Secret otočíte jedním kliknutím v zákaznické sekci a starý secret okamžitě přestane platit. Neúspěšné pokusy o ověření se zaznamenávají a omezují podle zdrojové IP, ale váš klíč nikdy nezablokují, takže nikdo nemůže zablokovat vaši integraci jen proto, že zná veřejné ID vašeho klíče.