Интеграция
Аутентификация и безопасность
API-ключ#
Каждый серверный вызов несёт два поля тела:
| Поле | Значение |
|---|---|
partner | id вашего проекта |
api_key | секретный ключ проекта |
Подписей и токенов в заголовках нет: ключ передаётся в теле JSON по HTTPS. Храните его только на сервере — не в браузере, мобильном приложении или логах. Запрос с неизвестным partner или неверным api_key получает HTTP 401 UNAUTHORIZED (эти два случая намеренно неразличимы).
Публичные методы только для чтения ключа не требуют: GET /games/health, GET /capabilities, GET /health, GET /docs/openapi.json.
Список разрешённых IP#
POST /gameActions.do и POST /playerRtp.do дополнительно требуют, чтобы IP-адрес вызывающего входил в одну из разрешённых для проекта сетей; иначе ответ — HTTP 403 IP_NOT_ALLOWED.
- Сети записываются в формате CIDR, IPv4 или IPv6 (
203.0.113.0/24,203.0.113.7/32,2001:db8::/32). - Список ведёт владелец платформы в админ-панели, раздел IP Whitelist — см. Доступ, персонал и история.
- Делайте все серверные вызовы с одних и тех же фиксированных адресов и просите разрешить именно их. Адреса IPv4 в виде IPv6 (
::ffff:a.b.c.d) считаются своей IPv4-формой.
Ротация API-ключа#
Владелец может показать или перевыпустить ключ в админ-панели (Projects → проект → Integration):
- Reveal показывает текущий ключ и записывается в журнал аудита.
- Regenerate просит ввести id проекта для подтверждения, создаёт новый ключ, а старый перестаёт работать немедленно. Если сбои вызовов недопустимы, подготовьте новый ключ на сервере заранее или будьте готовы развернуть его сразу.
- Панель показывает отпечаток (fingerprint) ключа — по нему можно понять, какой ключ используется на сервере, не раскрывая его.
У служебных проектов платформы (демо и кошелёк сайта) ключ доступен только для чтения.
Проверка callbacks платформы#
Платформа вызывает ваш кошелёк, передавая тот же api_key в теле JSON каждого callback. Сравнивайте его со своим ключом (за постоянное время) и отклоняйте запрос при несовпадении. Дополнительно:
- принимайте callbacks только на
https://-адресе под вашим контролем; - платформа не следует редиректам и ждёт ответ не более 2 секунд;
- адрес callback должен быть публичным:
https://, порт 443, без логина/пароля, query и фрагмента, без завершающего слэша, не длиннее 512 символов, хост только с публичными адресами.
Подробности и примеры: Callbacks кошелька.
Идемпотентность и повторы#
Изменяющие методы принимают заголовок Idempotency-Key, а каждая операция кошелька несёт уникальный id транзакции — оба защищают от дублей после тайм-аута. См. Соглашения.
Чек-лист безопасности#
- [ ] Ключ хранится в менеджере секретов или переменной окружения.
- [ ] Вызовы идут только с разрешённых серверов.
- [ ] Endpoint кошелька проверяет
api_key, работает по HTTPS и идемпотентен. - [ ] В логах нет ключа и
linkигры. - [ ] У сотрудников в админ-панели минимально необходимые права и проекты (Персонал).