Аутентификация

Каждый вызов интеграционного API идёт от имени сервисного аккаунта организации: клиента Keycloak с client credentials. Токен передают заголовком:

Authorization: Bearer <access_token>

Токен

• Токен выдаёт тот же realm Keycloak, через который входят сотрудники установки: https://<keycloak>/realms/<realm>/protocol/openid-connect/token, grant_type=client_credentials. Адрес показывает страница Интеграции → API организации.
• У токена должна быть аудитория helpdesk-integration-api: её добавляет маппер клиента Keycloak, запрашивать её отдельно не нужно.
• Токен пользователя (с сессией входа или человеческим логином) интеграционный API не принимает.
• SDK получают токен сами, держат его до истечения с запасом и обновляют один раз на 401.

Сервисный аккаунт

• Клиента в Keycloak создаёт и привязывает к организации администратор установки: организация не может занять чужой клиент. Организация видит свои аккаунты в Настройки → API и выбирает им роль.
• Организация берётся из записи аккаунта, а не из токена: один клиент действует за одну организацию.
• Права аккаунта — его роль на всю организацию. Отключённый аккаунт или отключённая организация получают отказ.
• Автор изменений в истории обращения и журнале аудита — система с меткой service:<client_id>. Заметку в рабочем месте оператора подписывает название аккаунта.

Роли

Роль	Что даёт
«Интеграция» (integration_sa)	чтение обращений, клиентов, справочников; начать обращение, сообщения и «печатает…» клиента, атрибуты клиента, ответы бота
«Интеграция: ведение обращений» (integration_operator)	всё из «Интеграции», а также закрыть, переоткрыть, передать, приоритет, тема, категория, метки, заметка, блокировка клиента, подписки на вебхуки
«Интеграция: отчёты» (integration_reports)	чтение обращений, монитор очередей, оценки, ответы форм, отчёты файлами (без имён клиентов)
«Интеграция: выгрузки» (integration_exports, привилегированная)	отчёты файлами с именами клиентов, выгрузки обращений с историей (текст фильтра ищется по сообщениям и заметкам) и клиентов с контактами
«Интеграция: журнал аудита» (integration_audit, привилегированная)	журнал аудита организации файлом, без чтения журнала в API
«Интеграция: конфигурация» (integration_config, привилегированная)	пакет конфигурации организации файлом, без ввоза; секреты в пакете — заглушки

Привилегированные роли при регистрации не выдаются. Смену роли на такую запрашивает один администратор организации, а одобряет другой (Настройки → API). До одобрения аккаунт работает с прежней ролью; запрос и одобрение пишутся в журнал аудита.

У каждой операции в справочнике указаны нужное право (x-helpdesk-permission) и роли, где оно есть (x-helpdesk-roles).

Отказы

Ответ	Что значит
401 UNAUTHENTICATED	нет токена, он истёк или подписан чужим realm, клиент не зарегистрирован сервисным аккаунтом
403 FORBIDDEN	роли аккаунта не хватает права или организация отключена
404 NOT_FOUND	объекта нет или он чужой организации: интеграционный API никогда не отвечает 403 на чужой объект

Конверт ответа — в разделе Ошибки.