KernelHost API

Co umożliwia KernelHost API (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 podpisywane za pomocą HMAC-SHA256, chronione przed atakami powtórzeniowymi, przetwarzane idempotentnie (w przypadku zamówień obowiązkowo) i zapisywane w odpornym na manipulacje dzienniku audytu. Płatności są pobierane najpierw z Państwa salda kredytowego, a następnie z zapisanej karty. Ze względów bezpieczeństwa nowe karty można dodawać wyłącznie w panelu klienta (3-D Secure 2).

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

Spis treści

• Szybki start w 5 minut
• Uwierzytelnianie (HMAC-SHA256)
• Referencja endpointów
• Kody błędów (RFC 7807)
• SDK i przykłady kodu
• 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ć ich status i wykonywać akcje: start, stop, reboot, anulowanie na koniec okresu rozliczeniowego oraz cofnięcie tego anulowania.
• 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.
• Zapisać dla każdego klucza własny URL webhooka. Dostarczanie zdarzeń (dotyczących zamówień, usług i faktur) jest w przygotowaniu; do tego czasu status mogą Państwo sprawdzać przez GET /v1/orders/{id} i GET /v1/services/{id}.

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/kernelhost_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 obecny klient KernelHost może w panelu klienta przez pozycję menu "KernelHost API" tworzyć klucze z własną etykietą, własnymi zakresami uprawnień i własną białą listą IP. Klucze może tworzyć, rotować i unieważniać wyłącznie właściciel konta. Osobna umowa resellerska nie jest potrzebna: wszystkie publicznie oferowane produkty można zamawiać przez API.

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

Kolejność płatności: najpierw Państwa saldo kredytowe, następnie zapisana metoda płatności. Jeżeli płatność się nie powiedzie lub nie zapisano żadnej karty, API zwraca HTTP 402 "Payment Required" z konkretnym powodem (insufficient_credit_and_no_card, card_declined, credit_apply_failed) i natychmiast anuluje zamówienie, dzięki czemu nie pozostaje żadne nieopłacone zamówienie.

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

Tak, wyłącznie dla własnych usług i wyłącznie z jawnym zakresem read:credentials, który trzeba osobno włączyć podczas tworzenia klucza. Odpowiedź zawiera nazwę hosta, adresy IP, nazwę użytkownika i hasło. Każdy dostęp powoduje utworzenie wpisu credentials.read w dzienniku audytu oraz wysłanie e-maila z potwierdzeniem na adres konta, dzięki czemu ukryte nadużycie nie pozostanie niezauważone.

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

Secret można zmienić jednym kliknięciem w panelu klienta, a poprzedni secret natychmiast traci ważność. Nieudane próby uwierzytelnienia są rejestrowane i ograniczane dla każdego źródłowego IP, ale nigdy nie blokują klucza, więc nikt nie zablokuje integracji tylko dlatego, że zna publiczny identyfikator klucza.