#Аутентификация и права

Статус: Доступно — ключи, области, права, список IP. Планируется — тестовые ключи и песочница.

Назначение: как устроены интеграции и ключи, что означают области, как вычисляются фактические права запроса, как ротировать и отзывать ключи и что делать при утечке.

#Модель: арендатор → интеграция → ключи

Арендатор
 └── Интеграция «Моя CRM»  (служебная учётная запись, без входа в кабинет)
      ├── роль интеграции (набор прав)
      ├── Ключ A  (области, срок, список IP, режим)
      └── Ключ B  (выпущен при ротации; Ключ A доживает до 24 ч)

• Интеграция — служебная учётная запись арендатора. В неё нельзя войти в кабинет; она не попадает в выбор операторов, рассылки и учёт мест. У неё своя роль и доступ ко всем диалогам арендатора.
• Ключи принадлежат интеграции. Ротация ключа не меняет идентификатор интеграции: ваши журналы и аудит остаются сквозными.
• За каждой интеграцией закреплён сотрудник-владелец — тот, кто её создал. От его текущих прав зависят права интеграции (см. ниже).
• На арендатора можно выпустить не более 20 активных ключей.
• Создавать интеграции и ключи может сотрудник с правом integrations.manage (по умолчанию — владелец и менеджер). Это право отдельное от управления ключами внешних поставщиков, которые платформа использует сама.

#Формат ключа

sap_<ячейка>_<режим>_<идентификатор>_<секрет>

Пример (заведомо ненастоящий):

sap_ru_test_EXAMPLE0KEYID_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEX

На стороне платформы хранится только необратимый хеш секрета с серверным «перцем» ячейки. Утечка базы без перца не раскрывает ключи.

#Как передавать ключ

Только в заголовке Authorization, только по TLS:

GET /api/public/v1/me HTTP/1.1
Host: formula-cream.pro
Authorization: Bearer sap_ru_live_EXAMPLE0KEYID_…

• Ключ нельзя передавать в адресе (?key=…), теле запроса или в cookie.
• В версии v1 подпись каждого запроса не требуется и не поддерживается: защита построена на Bearer-ключе по TLS. Усиленный режим на открытом ключе клиента (Ed25519) в v1 не поддерживается. Код signature_invalid зарезервирован для него и в v1 не возвращается.
• Браузер и мобильное приложение ключ получать не должны: используйте клиентские интерфейсы (Введение).

#Жизненный цикл ключа

#Пошаговая ротация без простоя

1. Выпустите новый ключ той же интеграции с теми же областями.
2. Разверните новый ключ в хранилище секретов и перезапустите сервисы.
3. Убедитесь по «Использованию API» в кабинете, что старый ключ больше не вызывается.
4. Отзовите старый ключ. Если забыли — он погаснет сам по окончании окна перекрытия.

#Области (scopes)

Область — право, которое вы даёте ключу. Выдавайте минимально необходимые. Колонка «Платно» — списывается ли плата с кошелька арендатора. Колонка «ПДн» — попадают ли в ответы персональные данные клиентов арендатора.

Примечания.

1. Стратег работает с агрегатами и не видит персональные данные по построению; это подтверждается при выпуске API.
2. Приём событий принимает только псевдонимные идентификаторы: anonymous_id и user_id — ваши собственные псевдонимы. Почта, телефон и имя в properties отклоняются ответом 422 validation_failed (JSON Pointer указывает поле), поэтому область не относится к ПДн.
3. POST /leads/{id}/score платный и требует leads:score. Запись собственной оценки внешней CRM (PUT /leads/{id}/score) бесплатна и требует leads:write.
4. Утверждение темы стратега и подтверждение его действия дополнительно требуют права на то, что предлагается выполнить, и доступного бюджета. Утверждение темы генерацию статьи не запускает.
5. GET /me, GET /wallet и GET /operations/{id} доступны любому действующему ключу и не требуют области (GET /me и GET /wallet работают и при остановленном обмене — Кошелёк); операции видны только той интеграции, которая их создала.
6. Подписка с include_pii: true дополнительно требует у интеграции leads:read и/или conversations:read (Вебхуки).
7. Журнал выдач ПДн виден арендатору в кабинете и по GET /disclosures (хранится 3 года). Какое право нужно ключу для этого запроса, в v1 не зафиксировано и будет указано в OpenAPI. Подробнее — Ячейки и данные.

#Соответствие областей и конечных точек

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

Запрос разрешён, только если каждое из условий выполнено. Фактические права — пересечение:

права запроса = области ключа
              ∩ роль интеграции
              ∩ ТЕКУЩИЕ права сотрудника-владельца
              ∩ лицензия (api_access) и тариф

Помимо этого действует проверка арендатора: арендатор должен быть активен. Идентификатор чужого ресурса даёт 404 not_found.

Следствие для интегратора: ключ, который работал вчера, может сегодня получить scope_missing, если права владельца изменились. Это нормальное поведение; обрабатывайте 403.

#Список разрешённых IP

• Необязательный: список адресов или сетей CIDR, с которых принимаются запросы ключа.
• Запрос с другого адреса — 403 ip_not_allowed.
• Для областей с ПДн (conversations:*, leads:*) в ячейке RU список IP интеграции обязателен; без него ключ с такими областями не выпускается. Дополнительно при подключении указываются страна размещения принимающей системы и основание передачи; если страна не РФ, области conversations:*, leads:* не выдаются (403 pii_transfer_not_allowed, Ячейки и данные). Текущий список виден в GET /me (key.ip_allowlist).
• Если вы запускаете вызовы из облака с плавающими адресами, закрепите исходящий адрес (NAT-шлюз, статический IP).
• Использование ключа с нового адреса или из новой страны вызывает тревогу владельцу арендатора.

#Тестовые ключи

Статус: Планируется.

Ключи с режимом test (sap_<ячейка>_test_…) работают в песочнице ячейки — отдельном арендаторе с вымышленными данными.

Боевой ключ не работает в песочнице, тестовый — в боевом арендаторе.

#Что делать при утечке ключа

1. Отзовите ключ в кабинете (Настройки → API). Отзыв действует не позже чем через 60 секунд.
2. Выпустите новый ключ и обновите секреты в своих системах.
3. Проверьте журнал «Использование API» (хранится 90 суток; в нём метод, маршрут, статус, время, стоимость, request_id — без тел запросов и ПДн) и аудит: что делал ключ после предполагаемой даты утечки.
4. Если у ключа были области с ПДн, проверьте журнал выдач ПДн (кабинет или GET /disclosures, хранится 3 года) и оцените, какие данные могли быть выданы. Обязанности оператора ПДн по уведомлению регуляторов и субъектов определяются законодательством вашей юрисдикции.
5. Проверьте, не создавались ли новые вебхуки, ключи и интеграции, и отзовите лишнее; при подозрении ротируйте секреты вебхуков.
6. Удалите ключ из истории репозитория и из логов; одного коммита-удаления мало.

Профилактика: минимальные области, список IP, срок жизни меньше максимального, отдельные ключи на отдельные системы, хранение в менеджере секретов.

#Ошибки аутентификации

Тело ответа — application/problem+json с type вида https://<домен ячейки>/developers/errors#<code> (Соглашения). Полный каталог — Соглашения.

#Заметки

• Каждая запись через API попадает в аудит арендатора с указанием интеграции и ключа (key_id), от имени служебной учётки.
• Брутфорс: поиск ключа идёт по key_id с сравнением за постоянное время; частые неудачи с одного адреса ограничиваются.
• CORS не поддерживается: прямой вызов API из браузера невозможен и не должен делаться.