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

Сваки захтев ка API интерфејсу платформе Sursa носи API кључ или OAuth приступни токен апликације у заглављу Authorization:

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.