Autentifikacija

Svaki zahtjev prema Sursa API-ju nosi API ključ ili OAuth pristupni token aplikacije u zaglavlju Authorization:

Authorization: Bearer kb_3f9c…

Ključ identificira organizaciju i određuje što zahtjev može vidjeti i promijeniti: njegova uloga, njegovi opsezi, njegov podatkovni profil i njegove zbirke. Na adresi API-ja nema sesija ni kolačića. Svaki se zahtjev autentificira zasebno, pa zahtjeve s istim ključem možete slati paralelno i s više poslužitelja.

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

Ranije integracije možda šalju ključ u zaglavlju X-API-Key. Ono se i dalje prihvaća, ali novi kod treba koristiti Authorization: Bearer.

Vrste vjerodajnica

Vjerodajnica	Izgled	Gdje radi
API ključ organizacije	`kb_…`	Sve operacije API-ja, u okviru njegove uloge, opsega, podatkovnog profila i zbirki.
Ključ vlastitog izvora	`kbsrc_…`	Samo operacije slanja (push) njegova vlastitog izvora (`/v1/push/sources/{source_id}/…`).
OAuth pristupni token	`kbat_…`	Operacije reference API-ja, u okviru opsega tokena. Token iz `POST /oauth/token` dobiven autorizacijskim kodom radi u ime zaposlenika koji je dao privolu; token `client_credentials` radi za organizaciju, kao API ključ. Vrijedi 1 sat.

Sve se vjerodajnice šalju na isti način. Ključ vlastitog izvora ne može čitati, pretraživati ni mijenjati ništa izvan svojeg izvora; koristite ga ondje gdje ključ pohranjuje treća strana, primjerice platforma za integracije.

Pogreške autentifikacije

Status i kod	Što znači	Što učiniti
`401` `auth.not_authenticated`	Ključa nema, pogrešno je upisan ili je opozvan.	Provjerite zaglavlje i vrijednost ključa.
`401` `api_keys.expired`	Ključu je istekao rok valjanosti.	Stvorite novi ključ i zamijenite stari.
`401` `sources.push_key_invalid`	Ključ vlastitog izvora pogrešan je, opozvan ili pripada drugom izvoru.	Provjerite ključ i ID izvora u putanji.
`401` `oauth.token_expired`	OAuth pristupnom tokenu istekao je rok valjanosti.	Dohvatite novi pomoću tokena za osvježavanje.
`403` `api_keys.scope`	Ključ nema opseg za ovu operaciju.	Dodajte opseg ili koristite ključ koji ga ima.
`403` `api_keys.feature_disabled`	Plan organizacije ne uključuje API ključeve.	Obratite se administratoru organizacije.
`403` `api_keys.ip_not_allowed`	Zahtjev dolazi s adrese izvan dopuštenih adresa ključa.	Pozovite API iz dopuštene mreže ili promijenite adrese ključa.
`403` `api_keys.mcp_only`	Osobni MCP ključ upotrijebljen je izvan operacije `/mcp`.	Za API koristite API ključ organizacije.
`403` `oauth.operation_not_allowed`	Operacija nije dio javnog API-ja, pa je OAuth token ne može pozvati.	Koristite operaciju iz reference API-ja.
`403` `org.suspended`	Organizacija je suspendirana. Njezini se podaci čuvaju.	Obratite se administratoru organizacije.

403 znači da je zahtjev autentificiran, ali nije dopušten. Objekt koji ključ ne smije vidjeti odgovara s 404, isto kao objekt koji ne postoji, pa ključ ne može saznati što se nalazi izvan njegova pristupa.

Rad u ime podatkovnog profila

Ključ s ulogom admin može provjeriti što bi vidjela neka druga skupina ljudi: zaglavlje X-View-As izvršava zahtjev u ime podatkovnog profila i, po želji, uloge.

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

Zahtjevi u ovom načinu rada samo čitaju: svaka promjena vraća 403 s kodom view_as.read_only. OAuth token ili ključ bez uloge admin ne može koristiti X-View-As: takav zahtjev vraća 403 s kodom view_as.admin_key_required. Zaglavlje koje ne navodi nijedan postojeći profil vraća 400 s kodom view_as.invalid_header.

Aplikacije u pregledniku

API dopušta zahtjeve s bilo kojeg web origina (Access-Control-Allow-Origin: *) i nikada ne koristi kolačiće, pa ga stranica može pozivati pomoću fetch. Ključ tada živi na stranici i vidljiv je svakome tko je koristi. API iz preglednika pozivajte samo s ključem koji ste spremni pokazati tim korisnicima, kao što je ključ s ulogom viewer ograničen na javne zbirke, ili između preglednika i Surse postavite vlastiti poslužitelj.

Što može samo zaposlenik

API ključ organizacije radi za organizaciju, a ne za osobu. Dva dijela API-ja pripadaju ljudima, pa rade samo s tokenom koji djeluje u ime zaposlenika: sa sesijom u Sursi ili s OAuth pristupnim tokenom izdanim uz privolu zaposlenika.

Razgovori pripadaju osobi. API ključ organizacije u GET /v1/conversations vidi samo razgovore koje je sam započeo. Javni API nema operaciju kojom se započinje razgovor, pa je za ključ popis obično prazan, a razgovori zaposlenika nikada mu se ne prikazuju. Pitanja bez razgovora, putem POST /v1/ask ili POST /v1/chat, rade sa svakim ključem koji ima opseg ask. Da biste dobili popis razgovora zaposlenika i pročitali povijest jednog od njih pomoću GET /v1/conversations/{conv_id}, pozovite API OAuth tokenom u ime tog zaposlenika. Token vidi samo vlastite razgovore tog zaposlenika; svaki drugi razgovor vraća 404 s kodom conversations.not_found.

Karticu provjerava samo zaposlenik. Provjera potvrđuje da je osoba pregledala sadržaj, pa POST /v1/cards/{card_id}/verification/verify i POST /v1/cards/{card_id}/verify zahtijevaju sesiju ili OAuth token u ime zaposlenika koji smije provjeriti karticu. S API ključem organizacije ili tokenom client_credentials vraćaju 400 s kodom cards.verify_user_account_required. Najprije se obavljaju uobičajene provjere pristupa: kartica koju ključ ne vidi vraća 404, a ključ koji je ne smije provjeriti dobiva 403.