Ключи и режимы

Страница для интегратора: как устроен ключ, что он может и почему тестовые данные не видны боевым ключом.

Формат

nbh_<режим>_<12 символов открытой части>_<32 символа секрета>

Открытая часть не секрет: по ней хаб находит запись ключа, не зная самого секрета. Секрет хранится только хешем (Argon2id) — восстановить его нельзя ни из базы, ни через поддержку.

Значение показывается один раз, при выпуске. Забытый ключ отзывается и выпускается заново; «покажите ещё раз» технически невозможно.

Режимы

nbh_test_… — песочница, nbh_live_… — бой. Это один и тот же API и один и тот же аккаунт; разделены только данные и исход отправки.

Изоляция строгая в обе стороны: объект другого режима отвечает 404 not_found — тем же ответом, что и несуществующий. Иначе тестовым ключом можно было бы перебором узнать, что существует в бою.

Режим ключа и режим объекта не смешиваются: ключ, чей режим разошёлся с записью, не работает вовсе.

Права

У ключа набор прав; лишних лучше не давать:

Право	Что открывает
send	отправка сообщений и пакетов
read	чтение сообщений, событий, пакетов, аккаунта
templates:write	заведение и правка шаблонов
webhooks:write	управление подписками на вебхуки

Запрос без нужного права — 403 insufficient_scope. Отдельного административного права у публичного API нет и не будет: административные действия живут во внутреннем контуре, куда ключом тенанта хода нет.

Ограничение по адресу

У ключа может быть список разрешённых адресов. Запрос с другого — отказ, даже если ключ верный. Список задаёт оператор хаба по вашей просьбе; для серверной интеграции с постоянными адресами это дешёвая защита от утёкшего ключа.

Хранение и утечка

• ключ — в переменной окружения или менеджере секретов, не в репозитории;
• в логи не пишется: хаб маскирует его в своих, вы — в своих;
• утёк — отзывайте немедленно. Отзыв действует со следующего запроса: ключ не кешируется на стороне хаба.

Перевыпуск без простоя: выпустите второй ключ, переключите на него код, отзовите первый. Ключей у аккаунта может быть несколько.

Что делать при 401

401 invalid_api_key означает одно из: ключа нет, он отозван, секрет не совпал, режим ключа разошёлся с записью. Какое именно — ответ не говорит намеренно: подбирающий не должен узнать по ответу, что подобрался ближе.

Слишком много неудачных попыток подряд с одного адреса — 429: вход ограничивает подбор. Обычной интеграции это не касается.