Reseller API: заказ хостинга через HMAC

Что умеет Reseller API

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

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

Базовый URL

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

Содержание

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

Получать список продуктов и цен (KVM-rootserver, выделенные серверы, веб-хостинг, Minecraft, VPN, безлимитный трафик).
Размещать заказы (Idempotency-Key защищает от двойного списания при сетевых повторах).
Получать список собственных услуг, проверять статус, выполнять действия (запуск, остановка, перезагрузка, переустановка, приостановка, удаление).
Читать учётные данные только собственных услуг (отдельное разрешение, журнал аудита, опциональное подтверждение по email при каждом доступе).
Получать счета, проверять баланс, скачивать PDF счетов.
Регистрировать вебхук на каждый ключ для событий заказов, услуг и счетов (схема подписи, совместимая со Stripe).

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

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/kh_reseller_api/v1/me \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG"

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

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

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

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

Порядок списания: сначала баланс, затем сохранённый способ оплаты (банковская карта с 3-D Secure 2). Если платёж отклонён или карта не привязана, API возвращает HTTP 402 "Payment Required" с конкретной причиной (insufficient_credit_and_no_card, card_declined, card_expired). Заказ остаётся в статусе "pending payment" 24 часа и затем автоматически отменяется.

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

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

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

Вы ротируете секрет одним кликом в клиентском портале. Старый секрет немедленно становится недействительным, все активные сессии аннулируются. При подозрительных ошибках аутентификации (5 за 10 минут) система автоматически блокирует ключ на 15 минут и отправляет вам уведомление по email.

Готовы начать?

Создайте свой первый API ключ в клиентском портале в разделе "Reseller API" и следуйте руководству быстрого старта.