Удостоверяване

Всяка заявка към Sursa API носи в заглавката Authorization API ключ или OAuth токен за достъп на приложение:

Authorization: Bearer kb_3f9c…

Ключът определя организацията и решава какво може да вижда и да променя заявката: неговата роля, неговите обхвати, профилът му за достъп и колекциите му. На адреса на 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`	Ключът на собствения източник е грешен, анулиран или принадлежи на друг източник.	Проверете ключа и ID на източника в пътя.
`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 означава, че заявката е удостоверена, но не е разрешена. Обект, който ключът няма право да вижда, отговаря с 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: отговорът е 403 с кода view_as.admin_key_required. Заглавка, която не назовава съществуващ профил, получава отговор 400 с кода view_as.invalid_header.

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

API разрешава заявки от всеки уеб origin (Access-Control-Allow-Origin: *) и никога не използва бисквитки, затова страницата може да го извиква с 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 токен от името на този служител. Токенът вижда само собствените разговори на служителя; всеки друг разговор отговаря с 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. Обичайните проверки се извършват преди това: карта, която ключът не вижда, отговаря с 404, а ключ, който няма право да я проверява, получава 403.