Ключи, права и лимиты
Права ключа, ограничение по IP, срок действия, коды ошибок и версии API.
Ключ арендатора — единственный способ вызывать /federation/v1/* с вашего сервера. Он принадлежит организации, несёт перечень прав и может быть ограничен по адресам и сроку.
Как передаётся ключ
Заголовок X-Recca-Tenant-Key: rtk_live_… на каждом запросе. Ключ — это rtk_live_ и 32 шестнадцатеричных символа; в базе хранится только его SHA-256, сам ключ показывается один раз при выпуске. В строке запроса, в теле и в JavaScript страницы ключу не место: он только серверный.
Проверка идёт на каждый запрос: ключ должен быть найден и не отозван, срок не вышел, организация активна, адрес вызова входит в список IP (если он задан); затем действует лимит запросов, а метод проверяет право ключа. Данные ключа сервер держит в кеше около пяти секунд, поэтому отзыв или смена прав вступают в силу не мгновенно, а в пределах нескольких секунд.
Права и группы прав
Право — строка семейство:объект:действие или объект:действие. Группа — всё до первого двоеточия. Экран выпуска показывает их под такими названиями:
| Группа | Название на экране | Права |
|---|---|---|
profile | Профили участников | profile:read |
users | Участники | users:read, users:upsert, users:impersonate |
shops | Витрины | shops:read |
offers | Офферы | offers:read |
leads | Заявки | leads:read, leads:write |
conversions | Конверсии | conversions:write, conversions:reverse |
tree | Реферальное дерево | tree:read |
badges | Бейджи | badges:read, badges:write |
promo | Промо | promo:read, promo:validate, promo:issue |
bonuses | Бонусы и балансы | bonuses:read |
cpa | CPA-сеть | cpa:self:read, cpa:self:write, cpa:partners:read, cpa:partners:write, cpa:offers:read, cpa:links:write, cpa:clicks:write, cpa:conversions:read, cpa:conversions:write, cpa:conversions:reverse, cpa:payouts:read, cpa:payouts:write, cpa:stats:read |
Семейство cpa:* отдельное сознательно: реферальные права offers:read, conversions:write и conversions:reverse не открывают денежную CPA-дверь. Выдавайте ключу ровно то, что нужно его задаче.
Право profile:email (добавляет в профили почту) через кабинет не выдаётся: попытка вернёт 400 SCOPE_NOT_SELF_SERVICE. Неизвестная строка вернёт 400 UNKNOWN_SCOPE. В одном ключе не больше 20 прав.
Методы GET /federation/v1/self и GET /federation/v1/health права не требуют. Остальные методы требуют своё: например, GET /federation/v1/offers — offers:read, POST /federation/v1/leads — leads:write, POST /federation/v1/conversions/{external_id}/reverse — conversions:reverse, GET /federation/v1/users/{id}/bonus-balance — bonuses:read. Нужное право каждого метода указано в справочнике OpenAPI и приходит в details.required ответа 403 INSUFFICIENT_SCOPE.
Только чтение
Флаг read_only при выпуске означает: все права ключа оканчиваются на :read. Это единственное определение чтения — права вроде promo:validate, promo:issue или users:upsert чтением не считаются, хотя слова «write» в них нет. Если вы выпускаете такой ключ запросом и кладёте в него не чтение, сервер ответит 400 READ_ONLY_VIOLATION и перечислит лишние права в details.offending.
Ограничение по IP
Список адресов и сетей CIDR (до 50 записей) задаётся при выпуске или позже (PATCH ключа меняет только список IP). Пустой список значит «без ограничения»: экран предупреждает об этом пометкой «любые IP». Вызов с адреса вне списка получает 403 IP_NOT_ALLOWED, а в details.client_ip — адрес, который увидел сервер. Неверная запись списка даёт 400 INVALID_CIDR с номером записи.
Адрес вызывающего сервер берёт из заголовка, который выставляет наш nginx, а не из того, что прислал клиент: подделать его заголовком X-Forwarded-For нельзя. Если вы идёте через собственный прокси или NAT, вносите в список его внешний адрес.
Срок действия
Форма предлагает 180 дней, но сервер срок не навязывает: ключ без срока выпускается, если срок снят осознанно. По истечении срока ключ перестаёт работать и отвечает как неизвестный — 401 INVALID_TENANT_KEY. За 14 дней и меньше до конца срока ключ в списке помечается «истекает». Перевыпускайте заранее: сначала новый ключ, затем отзыв старого.
Лимит запросов
Лимит считается на организацию, а не на ключ, в фиксированном окне 60 секунд, которое отсчитывается от первого запроса. По коду на момент написания: 1000 запросов в минуту для тарифов free и pro, 3000 — для organization и cpa_network. В каждом ответе есть X-RateLimit-Limit и X-RateLimit-Remaining. При превышении приходит 429 RATE_LIMIT_EXCEEDED с заголовком Retry-After (60 секунд) и details.limit. Пробы GET /federation/v1/health и GET /federation/v1/cpa/self в счёт не входят.
Конверт ошибки и коды
{
"success": false,
"error": { "code": "INSUFFICIENT_SCOPE", "message": "…", "details": { "required": "offers:read" } }
}
Ветвитесь по code: текст message контрактом не является и может меняться. Статусы кодов ниже закреплены, один код — один статус.
| Код | Статус | Когда |
|---|---|---|
MISSING_TENANT_KEY | 401 | нет заголовка X-Recca-Tenant-Key |
INVALID_TENANT_KEY | 401 | ключ не найден, отозван, просрочен или организация отключена |
MISSING_TENANT_SCOPE | 401 | права ключа не определились |
INSUFFICIENT_SCOPE | 403 | у ключа нет нужного права |
IP_NOT_ALLOWED | 403 | адрес вне списка IP ключа |
RATE_LIMIT_EXCEEDED | 429 | исчерпан лимит запросов |
INVALID_INPUT, VALIDATION_ERROR | 400 | тело или параметры не прошли проверку |
RESERVED_EXTERNAL_ID | 400 | external_id из зарезервированного пространства recca: |
NOT_A_MEMBER, USER_NOT_MEMBER_OF_TENANT | 403 | человек не участник вашей сети (два кода об одном; обрабатывайте оба) |
NOT_FOUND, OFFER_NOT_FOUND, PROGRAM_NOT_FOUND | 404 | предмета нет либо он вне видимости вашей сети |
REDEMPTION_NOT_FOUND | 404 | погашение с таким идентификатором в вашей сети не найдено |
CONFLICT, PROGRAM_INACTIVE | 409 | конфликт состояния |
NO_REFERRER_TO_REWARD, LEG_AMOUNT_MISMATCH | 409 | погашение: награждать некому (кампанийный код с анонимным получателем) либо нога каскада уже есть с другой суммой |
INTERNAL_ERROR | 500 | сбой на нашей стороне; повтор оправдан, назовите X-Request-Id |
TENANT_HAS_NO_SHOP | 500 | погашение: у сети нет витрины, к которой привязать бонусный счёт; причина на стороне сети |
Методы CPA-двери (/federation/v1/cpa/*) добавляют свои коды — PARTNER_NOT_FOUND, ALREADY_CONVERTED, IDEMPOTENT_MISMATCH, BELOW_MIN_PAYOUT, INSUFFICIENT_BALANCE и другие; они перечислены в разделе «CPA-API». Дверь CPA закрыта, пока у организации не подключён продукт «CPA-сеть»: 403 FEATURE_NOT_AVAILABLE, а если продукт приостановлен — 403 PRODUCT_PAUSED; оба состояния относятся к подписке, повтор запроса их не меняет.
Версии API
Версия — часть пути: /federation/v1/…, /embed/v1/…. Совместимые изменения (новое необязательное поле запроса, новое поле ответа, новый метод, новый код ошибки на новом условии) выходят внутри v1 без предупреждения, поэтому не падайте на незнакомых полях ответа. Ломающие изменения (пропавшее поле, смена типа, смена статуса кода, смена канона подписи) выходят новой мажорной версией пути. По правилам политики версий прежняя версия живёт не меньше 12 месяцев, а на устаревших путях приходят заголовки Deprecation и Sunset.
Сегодня устаревших путей два вида. Первый — идентификатор человека в путях /federation/v1/users/{id}/…: сырой внутренний идентификатор Recca принимается до 31 декабря 2026 года и сопровождается заголовками Deprecation: true и Sunset. Второй — прежние адреса виджетов без версии (/embed/badge/{user_id}, /embed/login-button): они отвечают 301 на адреса /embed/v1/… с теми же заголовками. Ответа 410 на устаревших путях сегодня нет, и срок отключения считайте ориентиром, а не гарантией работы после даты. Вместо него используйте tenant_recca_id — суррогат из 16 символов, который возвращает POST /federation/v1/users/upsert.
Версия контракта CPA-двери (дата) отдаётся в GET /federation/v1/cpa/self: сверяйте её при запуске.
Отзыв и ротация
Ключ отзывается на странице «API-ключи» кнопкой отзыва; отозванный ключ сразу (с задержкой кеша) получает 401 INVALID_TENANT_KEY. Ключ с утечкой отзывайте немедленно, не дожидаясь замены. Для ротации выпустите новый ключ с теми же правами, переключите сервис, проверьте GET /federation/v1/self и только потом отзовите старый.
См. также
- Быстрый старт — от ключа до первого вызова
- CPA-API — права CPA-двери по методам
- Федерация (tenant API) — методы федерации и их права
- Вебхуки — подпись и повторы доставки
- Справочник OpenAPI — описание методов и версия контракта