Интеграция
Аутентификация и безопасность
API-ключ#
Каждый серверный вызов содержит два поля тела:
| Поле | Значение |
|---|---|
partner | Идентификатор вашего проекта |
api_key | Секретный ключ вашего проекта |
Запросы к платформе не используют токены в заголовках: ключ передаётся в JSON-теле поверх HTTPS. Храните его только на сервере: не в браузере, не в мобильном приложении, не в логах. Запрос с неизвестным partner или неверным api_key получает HTTP 401 UNAUTHORIZED; эти два случая намеренно неразличимы.
Публичные read-only endpoints ключа не требуют: GET /games/health, GET /games/catalog, GET /capabilities, GET /health, GET /docs/openapi.json (Каталог).
Список разрешённых IP#
POST /gameActions.do (фриспины, целевые исходы, round_cancel, report_*) и POST /playerRtp.do дополнительно требуют, чтобы IP-адрес вызывающего входил в одну из сетей, разрешённых для проекта. Сначала проверяется ключ, затем адрес: неверный ключ даёт UNAUTHORIZED, верный ключ с адреса вне списка — HTTP 403 IP_NOT_ALLOWED.
- Сети записываются в формате CIDR, IPv4 или IPv6 (
203.0.113.0/24,203.0.113.7/32,2001:db8::/32). - Список ведут в админ-панели, раздел IP Whitelist, владелец платформы или ваши сотрудники с правом manage credentials (см. Админ-панель).
- Делайте все серверные вызовы с одних и тех же постоянных адресов и просите разрешить именно их. IPv4-mapped IPv6-адреса считаются своей IPv4-формой.
Ротация и отзыв API-ключа#
В админ-панели (Projects → проект → Integration) владелец платформы и ваши сотрудники с правом manage credentials могут перевыпустить и отозвать ключ:
- Regenerate (ротация) требует ввести идентификатор проекта для подтверждения, создаёт новый ключ, а старый ключ перестаёт работать сразу. Если сбои вызовов недопустимы, установите новый ключ на сервере до перевыпуска либо будьте готовы развернуть его немедленно. Секрет подписи колбэков, выводимый из ключа, меняется вместе с ним (Подпись колбэков).
- Revoke отключает ключ без выпуска нового: ни один ключ не подходит, и каждый вызов отвечает
UNAUTHORIZED, пока ключ не будет создан заново. - Reveal показывает текущий ключ, записывается в журнал аудита и доступно только владельцу.
- Панель показывает отпечаток ключа, чтобы можно было понять, какой ключ использует сервер, не раскрывая его.
У внутренних проектов платформы (демо и кошелёк сайта) ключ доступен только для чтения.
Проверка колбэков платформы#
Платформа вызывает ваш кошелёк с тем же api_key в JSON-теле каждого колбэка. Сравнивайте его со своим ключом (за постоянное время) и отклоняйте запрос при несовпадении. Кроме того, каждый колбэк подписан HMAC-SHA256 (X-Notell-Timestamp, X-Notell-Signature; каноническая строка, секрет и тестовый вектор — в Подписи колбэков) и приходит с фиксированных адресов из callbackSourceIps в GET /capabilities; разрешите их. Также:
- принимайте колбэки только на
https://-адресе, который вы контролируете; - платформа не следует редиректам и ждёт ответа не более 2 секунд;
- URL колбэка должен быть публичным:
https://, порт 443, без user info, query и fragment, без завершающего слэша, не длиннее 512 символов, а хост должен разрешаться только в публичные адреса.
Управление соединением, повторы и формат ответа: Колбэки кошелька.
Квоты и повторы#
Квоты запросов на проект и заголовок Idempotency-Key описаны один раз, в Соглашениях. Каждая операция кошелька несёт уникальный meta.transaction, который защищает кошелёк от дублей после таймаута.
Чек-лист безопасности#
- [ ] Ключ хранится в менеджере секретов или переменной окружения.
- [ ] Вызовы идут только с серверов из списка разрешённых.
- [ ] Endpoint кошелька проверяет
api_keyиX-Notell-Signature, работает по HTTPS, идемпотентен и принимает только IP колбэков платформы. - [ ] В логах нет ключа и
linkигры. - [ ] У сотрудников в админ-панели минимально необходимые права и проекты.