Автентифікація

Кожен запит до Sursa API містить ключ API або токен доступу OAuth застосунку в заголовку Authorization:

Authorization: Bearer kb_3f9c…

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

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`	Ключ власного джерела неправильний, відкликаний або належить іншому джерелу.	Перевірте ключ та ID джерела в шляху.
`401` `oauth.token_expired`	Строк дії токена доступу OAuth минув.	Отримайте новий токен за допомогою токена оновлення.
`403` `api_keys.scope`	Ключ не має області доступу для цієї операції.	Додайте область доступу або використайте ключ, у якого вона є.
`403` `api_keys.feature_disabled`	Тариф організації не містить ключів API.	Зверніться до адміністратора організації.
`403` `api_keys.ip_not_allowed`	Запит надходить з адреси поза дозволеними адресами ключа.	Викликайте API з дозволеної мережі або змініть адреси ключа.
`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.