KernelHost API

Что умеет KernelHost API (Reseller API)

KernelHost Reseller API повторяет ровно те действия по заказу и управлению, которые вы иначе выполняли бы кликами в клиентском портале. Он позволяет автоматизировать ваш реселлерский бизнес, интегрировать продукты KernelHost в собственный фронтенд или биллинг и сохранять полный контроль над разрешениями, ограничениями частоты и белыми списками IP по каждому ключу.

Каждый вызов подписывается HMAC-SHA256, защищён от повторной отправки, обрабатывается идемпотентно (для заказов это обязательно) и фиксируется в защищённом от подделки журнале аудита. Платежи списываются сначала с вашего баланса, затем с сохранённой карты. Из соображений безопасности новые карты можно добавить только в клиентском портале (3-D Secure 2).

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

Содержание

• Быстрый старт за 5 минут
• Аутентификация (HMAC-SHA256)
• Справочник endpoint
• Коды ошибок (RFC 7807)
• SDK и примеры кода
• Безопасность и лучшие практики
• История изменений

Что вы можете делать

• Получать список продуктов и цен (KVM-rootserver, выделенные серверы, веб-хостинг, Minecraft, VPN, безлимитный трафик).
• Размещать заказы (Idempotency-Key защищает от двойного списания при сетевых повторах).
• Получать список собственных услуг, проверять их статус и выполнять действия: запуск, остановка, перезагрузка, отмена по окончании расчётного периода и отзыв этой отмены.
• Читать учётные данные только собственных услуг (отдельное разрешение, журнал аудита, опциональное подтверждение по email при каждом доступе).
• Получать счета, проверять баланс, скачивать PDF счетов.
• Указывать для каждого ключа свой URL вебхука. Доставка событий (по заказам, услугам и счетам) находится в разработке; до тех пор запрашивайте статус через GET /v1/orders/{id} и GET /v1/services/{id}.

Дизайн максимальной безопасности

API спроектирован исходя из того, что каждый вызов имеет прямое финансовое влияние и может раскрыть чувствительные учётные данные сервера. Поэтому базовый уровень безопасности существенно выше типичного REST.

• Подпись HMAC-SHA256 по методу, пути, временной метке, nonce и хешу тела. Сравнение за константное время.
• Защита от повторов: окно временной метки +-300с, кэш одноразовых nonce на 600с.
• Секреты хранятся исключительно в виде шифротекста AES-256-GCM. Открытый текст существует только временно в памяти для верификации подписи. Мастер-ключ хранится вне базы данных.
• Гранулярные разрешения по каждому ключу. Опасные разрешения (read:credentials, write:orders) должны быть включены явно. По умолчанию — только чтение.
• Изоляция данных на уровне базы: каждый запрос жёстко фильтруется по идентификатору вашего аккаунта. Межарендный доступ невозможен по архитектуре.

Пример: запрос информации о собственном аккаунте

Запрос подписывается целиком вашим секретом. Секрет никогда не покидает память клиента; передаётся только подпись.

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"

Часто задаваемые вопросы

Кто может пользоваться Reseller API?

Любой действующий клиент KernelHost может создавать ключи в клиентском портале через пункт меню "KernelHost API", каждый с собственной меткой, разрешениями и белым списком IP. Создавать, ротировать и отзывать ключи может только владелец аккаунта. Отдельное реселлерское соглашение не требуется: все публично продаваемые продукты можно заказать через API.

Как оплачиваются заказы?

Порядок списания: сначала с вашего баланса, затем с сохранённого способа оплаты. Если платёж не прошёл или карта не привязана, API возвращает HTTP 402 "Payment Required" с точной причиной (insufficient_credit_and_no_card, card_declined, credit_apply_failed) и сразу отменяет заказ, так что неоплаченных заказов не остаётся.

Можно ли читать пароли услуг через API?

Да, но только для ваших собственных услуг и только с явным разрешением read:credentials, которое нужно отдельно включить при создании ключа. Ответ содержит имя хоста, IP-адреса, имя пользователя и пароль. Каждое обращение создаёт запись credentials.read в журнале аудита и отправляет письмо с подтверждением на email-адрес аккаунта, поэтому скрытое злоупотребление не останется незамеченным.

Что делать, если мой секрет скомпрометирован?

Вы меняете secret одним кликом в личном кабинете, и старый secret сразу становится недействительным. Неудачные попытки аутентификации регистрируются и ограничиваются для каждого исходного IP, но никогда не блокируют Ваш ключ, поэтому никто не сможет заблокировать Вашу интеграцию, просто зная публичный ID ключа.