KernelHost Reseller API

Co umożliwia Reseller API

KernelHost Reseller API odwzorowuje dokładnie te same akcje zamawiania i zarządzania, które w innym wypadku wykonują Państwo poprzez kliknięcia w panelu klienta. Pozwala zautomatyzować Państwa działalność reselerską, zintegrować produkty KernelHost z własnym frontendem lub systemem rozliczeń oraz zachować pełną kontrolę nad zakresami uprawnień, limitami szybkości i białą listą IP dla każdego klucza.

Każde wywołanie jest podpisane HMAC-SHA256, chronione przed atakiem powtórzenia, przetwarzane idempotentnie (obowiązkowo dla zamówień), zapisywane w odpornym na manipulacje dzienniku audytu i opcjonalnie potwierdzane przez webhook. Płatności są pobierane najpierw z salda kredytowego, następnie z zapisanej karty. Nowe karty można dodawać wyłącznie w panelu klienta (wymuszone 3-D Secure 2).

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

Spis treści

• Szybki start w 5 minut
• Uwierzytelnianie (HMAC-SHA256)
• Referencja endpointów
• Kody błędów (RFC 7807)
• SDK: PHP, Node.js, Python, Go
• Bezpieczeństwo i dobre praktyki
• Lista zmian

Co można zrobić

• Przeglądać produkty i ceny (serwery KVM root, dedykowane, webspace, Minecraft, VPN, ruch bez limitu).
• Składać zamówienia (nagłówek Idempotency-Key chroni przed podwójnymi obciążeniami przy ponownych próbach sieciowych).
• Wyświetlać własne usługi, sprawdzać status, wykonywać akcje (start, stop, restart, reinstalacja, zawieszenie, terminacja).
• Odczytywać dane dostępowe wyłącznie własnych usług (oddzielny zakres uprawnień, wpis w audycie, opcjonalny e-mail potwierdzający przy każdym dostępie).
• Pobierać faktury, sprawdzać saldo kredytowe, ściągać PDF faktur.
• Rejestrować webhook dla każdego klucza dla zdarzeń zamówień, usług i faktur (schemat podpisu zgodny ze Stripe).

Projekt o maksymalnym poziomie bezpieczeństwa

API zostało zaprojektowane przy założeniu, że każde wywołanie ma bezpośredni wpływ finansowy i może udostępniać poufne dane dostępowe do serwerów. Wymagania bezpieczeństwa leżą zatem znacznie powyżej zwykłego standardu REST.

• Podpis żądania HMAC-SHA256 obejmuje metodę, ścieżkę, znacznik czasu, nonce i skrót treści. Porównanie w czasie stałym.
• Ochrona przed powtórzeniem: okno tolerancji znacznika czasu +-300s, jednorazowa pamięć podręczna nonce przez 600s.
• Tajne klucze są utrwalane wyłącznie jako szyfrogramy AES-256-GCM. Tekst jawny istnieje przejściowo w pamięci tylko podczas weryfikacji podpisu. Klucz główny znajduje się poza bazą danych.
• Szczegółowe zakresy uprawnień dla każdego klucza. Niebezpieczne zakresy (read:credentials, write:orders) muszą być włączone w sposób jawny. Domyślnie tylko do odczytu.
• Izolacja danych na poziomie bazy danych: każde zapytanie filtruje w sposób twardy po identyfikatorze Państwa konta. Dostęp międzylokatorski jest niemożliwy z założenia.

Przykład: zapytanie o własne konto

Żądanie jest podpisywane w całości Państwa tajnym kluczem. Tajny klucz nigdy nie opuszcza pamięci klienta; przesyłany jest wyłącznie 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"

Najczęściej zadawane pytania

Kto może korzystać z Reseller API?

Każdy istniejący klient KernelHost może w sekcji "Moje konto → Reseller API" utworzyć klucz z własną etykietą, zakresami uprawnień i białą listą IP. Osobna umowa partnerska nie jest wymagana: każdy publicznie oferowany produkt jest dostępny przez API.

W jaki sposób opłacane są zamówienia?

Kolejność: najpierw saldo kredytowe, następnie zapisana metoda płatności (karta kredytowa z 3-D Secure 2). Jeżeli płatność zostanie odrzucona lub żadna karta nie jest zapisana, API zwraca HTTP 402 "Payment Required" z konkretnym powodem (insufficient_credit_and_no_card, card_declined, card_expired). Zamówienie pozostaje przez 24h w stanie "pending payment", a następnie zostaje automatycznie anulowane.

Czy mogę odczytywać hasła usług przez API?

Tak, ale wyłącznie dla własnych usług i wyłącznie z jawnym zakresem read:credentials, który należy włączyć podczas tworzenia klucza. Każdy dostęp generuje wpis w dzienniku audytu credentials.read; na życzenie mogą Państwo dodatkowo otrzymywać e-mail potwierdzający na adres konta, dzięki czemu ciche nadużycie jest niemożliwe.

Co się stanie, jeśli mój tajny klucz zostanie skompromitowany?

Tajny klucz mogą Państwo zrotować jednym kliknięciem w panelu klienta. Stary klucz zostaje natychmiast unieważniony, wszystkie aktywne sesje są wycofywane. Przy podejrzanych nieudanych uwierzytelnieniach (5 w ciągu 10 minut) system automatycznie blokuje klucz na 15 minut i informuje Państwa pocztą elektroniczną.