Autentifikácia

Každá požiadavka na Sursa API nesie v hlavičke Authorization kľúč API alebo prístupový token OAuth aplikácie:

Authorization: Bearer kb_3f9c…

Kľúč identifikuje organizáciu a rozhoduje, čo požiadavka smie vidieť a meniť: jeho rola, rozsahy, dátový profil a kolekcie. Na adrese API nie sú relácie ani súbory cookie. Každá požiadavka sa overuje samostatne, takže s tým istým kľúčom môžete posielať požiadavky súbežne a z viacerých serverov.

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

Staršie integrácie môžu namiesto toho posielať kľúč v hlavičke X-API-Key. Stále sa prijíma, ale nový kód by mal používať Authorization: Bearer.

Druhy prihlasovacích údajov

Prihlasovacie údaje	Tvar	Kde fungujú
Kľúč API organizácie	`kb_…`	Všetky operácie API v rámci jeho roly, rozsahov, dátového profilu a kolekcií.
Kľúč vlastného zdroja	`kbsrc_…`	Len operácie push toho vlastného zdroja, ku ktorému patrí (`/v1/push/sources/{source_id}/…`).
Prístupový token OAuth	`kbat_…`	Operácie referencie API v rámci rozsahov tokenu. Token z `POST /oauth/token` získaný autorizačným kódom koná v mene zamestnanca, ktorý dal súhlas; token `client_credentials` koná za organizáciu ako kľúč API. Platí 1 hodinu.

Všetky sa posielajú rovnako. Kľúč vlastného zdroja nemôže nič čítať, vyhľadávať ani meniť mimo svojho zdroja; používajte ho tam, kde kľúč uchováva tretia strana, napríklad integračná platforma.

Chyby autentifikácie

Stav a kód	Čo znamená	Čo robiť
`401` `auth.not_authenticated`	Chýba kľúč, kľúč je zle zadaný alebo odvolaný.	Skontrolujte hlavičku a hodnotu kľúča.
`401` `api_keys.expired`	Kľúču uplynul dátum vypršania platnosti.	Vytvorte nový kľúč a nahraďte ním starý.
`401` `sources.push_key_invalid`	Kľúč vlastného zdroja je nesprávny, odvolaný alebo patrí inému zdroju.	Skontrolujte kľúč a ID zdroja v ceste.
`401` `oauth.token_expired`	Platnosť prístupového tokenu OAuth vypršala.	Získajte nový pomocou obnovovacieho tokenu.
`403` `api_keys.scope`	Kľúč nemá rozsah pre túto operáciu.	Pridajte rozsah alebo použite kľúč, ktorý ho má.
`403` `api_keys.feature_disabled`	Tarifa organizácie nezahŕňa kľúče API.	Obráťte sa na administrátora organizácie.
`403` `api_keys.ip_not_allowed`	Požiadavka prichádza z adresy, ktorá nie je medzi povolenými adresami kľúča.	Volajte z povolenej siete alebo zmeňte adresy kľúča.
`403` `api_keys.mcp_only`	Osobný kľúč MCP bol použitý mimo operácie `/mcp`.	Na prácu s API použite kľúč API organizácie.
`403` `oauth.operation_not_allowed`	Operácia nie je súčasťou verejného API, preto ju token OAuth nemôže volať.	Použite operáciu z referencie API.
`403` `org.suspended`	Organizácia je pozastavená. Jej údaje sa uchovávajú.	Obráťte sa na administrátora organizácie.

403 znamená, že požiadavka bola overená, ale nie je povolená. Objekt, ktorý kľúč nesmie vidieť, odpovie 404 rovnako ako objekt, ktorý neexistuje, takže kľúč sa nemôže dozvedieť, čo leží mimo jeho prístupu.

Práca v mene dátového profilu

Kľúč s rolou admin môže overiť, čo by videla iná skupina ľudí: hlavička X-View-As vykoná požiadavku v mene dátového profilu a voliteľne aj roly.

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

Požiadavky v tomto režime len čítajú: každá zmena vráti 403 s kódom view_as.read_only. Token OAuth ani kľúč bez roly admin nemôže X-View-As použiť: požiadavka vráti 403 s kódom view_as.admin_key_required. Hlavička, ktorá neuvádza žiadny existujúci profil, vráti 400 s kódom view_as.invalid_header.

Aplikácie v prehliadači

API povoľuje požiadavky z ľubovoľného webového pôvodu (Access-Control-Allow-Origin: *) a nikdy nepoužíva súbory cookie, takže stránka ho môže volať cez fetch. Kľúč je potom súčasťou stránky a vidí ho každý, kto ju používa. Z prehliadača volajte API len s kľúčom, ktorý ste ochotní týmto používateľom ukázať, napríklad s kľúčom viewer obmedzeným na verejné kolekcie, alebo medzi prehliadač a Sursu vložte vlastný server.

Čo môže urobiť len zamestnanec

Kľúč API organizácie koná za organizáciu, nie za človeka. Dve časti API patria ľuďom, preto fungujú len s tokenom, ktorý koná v mene zamestnanca: s reláciou v Surse alebo s prístupovým tokenom OAuth vydaným so súhlasom zamestnanca.

Konverzácie patria človeku. Kľúč API organizácie vidí v GET /v1/conversations len konverzácie, ktoré sám začal. Verejné API nemá operáciu, ktorá konverzáciu začína, preto je zoznam pre kľúč zvyčajne prázdny a konverzácie zamestnancov sa mu nikdy nezobrazia. Otázky bez konverzácie cez POST /v1/ask alebo POST /v1/chat fungujú s každým kľúčom, ktorý má rozsah ask. Ak chcete vypísať konverzácie zamestnanca a čítať históriu jednej z nich cez GET /v1/conversations/{conv_id}, volajte API s tokenom OAuth v mene tohto zamestnanca. Token vidí len vlastné konverzácie tohto zamestnanca; každá iná konverzácia vráti 404 s kódom conversations.not_found.

Kartu overuje len zamestnanec. Overenie potvrdzuje, že obsah skontroloval človek, preto POST /v1/cards/{card_id}/verification/verify a POST /v1/cards/{card_id}/verify vyžadujú reláciu alebo token OAuth v mene zamestnanca, ktorý smie kartu overiť. S kľúčom API organizácie alebo s tokenom client_credentials vrátia 400 s kódom cards.verify_user_account_required. Najprv prebehnú bežné kontroly: karta, ktorú kľúč nevidí, vráti 404, a kľúč, ktorý ju nesmie overiť, dostane 403.