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

Каждый запрос к Sursa API передаёт ключ API или токен доступа OAuth приложения в заголовке Authorization:

Authorization: Bearer kb_3f9c…

Ключ определяет организацию и то, что запрос может видеть и менять: роль ключа, его области, профиль доступа и коллекции. Сессий и cookie на адресе API нет. Каждый запрос проходит аутентификацию сам по себе, поэтому с одним и тем же ключом можно отправлять запросы параллельно и с нескольких серверов.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Прежние интеграции могут передавать ключ в заголовке X-API-Key. Он по-прежнему принимается, но в новом коде используйте Authorization: Bearer.

Виды учётных данных

Учётные данные	Как выглядят	Где работают
Ключ API организации	`kb_…`	Все операции API в пределах роли, областей, профиля доступа и коллекций ключа.
Ключ своего источника	`kbsrc_…`	Только push-операции того своего источника, к которому относится ключ (`/v1/push/sources/{source_id}/…`).
Токен доступа OAuth	`kbat_…`	Операции справочника API в пределах областей токена. Токен из `POST /oauth/token`, полученный по коду авторизации, действует от имени сотрудника, который дал согласие; токен `client_credentials` действует от имени организации, как ключ API. Срок действия токена — 1 час.

Все они передаются одинаково. Ключ своего источника не может читать, искать или менять что-либо за пределами своего источника. Используйте его там, где ключ хранит третья сторона, например платформа интеграций.

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

Статус и код	Что означает	Что делать
`401` `auth.not_authenticated`	Ключа нет, в нём опечатка или он отозван.	Проверьте заголовок и значение ключа.
`401` `api_keys.expired`	Срок действия ключа истёк.	Создайте новый ключ и замените им старый.
`401` `sources.push_key_invalid`	Ключ своего источника неверен, отозван или принадлежит другому источнику.	Проверьте ключ и идентификатор источника в пути.
`401` `oauth.token_expired`	Срок действия токена доступа OAuth истёк.	Получите новый токен с помощью токена обновления.
`403` `api_keys.scope`	У ключа нет области для этой операции.	Добавьте область или используйте ключ, у которого она есть.
`403` `api_keys.feature_disabled`	Тариф организации не включает ключи API.	Обратитесь к администратору организации.
`403` `api_keys.ip_not_allowed`	Запрос пришёл с адреса, которого нет среди разрешённых адресов ключа.	Отправьте запрос из разрешённой сети или измените адреса ключа.
`403` `api_keys.mcp_only`	Личный ключ MCP использован не для операции `/mcp`.	Для API используйте ключ API организации.
`403` `oauth.operation_not_allowed`	Операция не входит в публичный API, поэтому токен OAuth не может её вызвать.	Используйте операцию из справочника API.
`403` `org.suspended`	Работа организации приостановлена. Её данные сохраняются.	Обратитесь к администратору организации.

403 означает, что запрос прошёл аутентификацию, но не разрешён. На объект, который ключу видеть нельзя, API отвечает 404 — так же, как на объект, которого не существует. Поэтому ключ не может узнать, что лежит за пределами его доступа.

Запросы от имени профиля доступа

Ключ с ролью admin может проверить, что увидела бы другая группа людей: заголовок X-View-As выполняет запрос от имени профиля доступа и, если нужно, другой роли.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

В этом режиме запросы только читают: любое изменение возвращает 403 с кодом view_as.read_only. Токен OAuth или ключ без роли admin не может использовать X-View-As: на такой запрос API отвечает 403 с кодом view_as.admin_key_required. Если заголовок называет несуществующий профиль, API отвечает 400 с кодом view_as.invalid_header.

Приложения в браузере

API принимает запросы с любого веб-источника (Access-Control-Allow-Origin: *) и никогда не использует cookie, поэтому страница может вызывать его через fetch. Ключ тогда находится в странице, и его видит каждый, кто ею пользуется. Вызывайте API из браузера только с ключом, который не страшно показать этим пользователям, например с ключом роли viewer, ограниченным общедоступными коллекциями. Другой вариант — поставить свой сервер между браузером и Sursa.

Что может только сотрудник

Ключ API организации действует от имени организации, а не человека. Две части API принадлежат людям, поэтому они работают только с токеном, который действует от имени сотрудника: с сессией в Sursa или с токеном доступа OAuth, выданным с согласия сотрудника.

Беседы принадлежат человеку. Ключ API организации видит в GET /v1/conversations только беседы, которые начал он сам. В публичном API нет операции, которая начинает беседу, поэтому для ключа этот список обычно пуст, а беседы сотрудников ему не показываются никогда. Вопросы без беседы — через POST /v1/ask или POST /v1/chat — работают с любым ключом, у которого есть область ask. Чтобы получить список бесед сотрудника и прочитать историю одной из них через GET /v1/conversations/{conv_id}, вызывайте API с токеном OAuth от имени этого сотрудника. Токен видит только собственные беседы сотрудника; на любую другую беседу API отвечает 404 с кодом conversations.not_found.

Подтвердить карточку может только сотрудник. Верификация подтверждает, что содержимое проверил человек, поэтому POST /v1/cards/{card_id}/verification/verify и POST /v1/cards/{card_id}/verify требуют сессии или токена OAuth от имени сотрудника, которому разрешено подтверждать эту карточку. С ключом API организации или токеном client_credentials они отвечают 400 с кодом cards.verify_user_account_required. Сначала выполняются обычные проверки: на карточку, которую ключ не видит, API отвечает 404, а ключу, которому нельзя её подтверждать, — 403.