Autentifikavimas

Kiekviena užklausa Sursa API antraštėje Authorization perduoda API raktą arba programos OAuth prieigos žetoną:

Authorization: Bearer kb_3f9c…

Raktas identifikuoja organizaciją ir lemia, ką užklausa gali matyti ir keisti: jo vaidmuo, apimtys, duomenų profilis ir rinkiniai. API adresu nėra nei sesijų, nei slapukų. Kiekviena užklausa autentifikuojama atskirai, todėl su tuo pačiu raktu užklausas galima siųsti lygiagrečiai ir iš kelių serverių.

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

Ankstesnės integracijos raktą gali siųsti antraštėje X-API-Key. Ji vis dar priimama, bet naujame kode naudokite Authorization: Bearer.

Prisijungimo duomenų rūšys

Prisijungimo duomenys	Kaip atrodo	Kur veikia
Organizacijos API raktas	`kb_…`	Visos API operacijos, neperžengiant jo vaidmens, apimčių, duomenų profilio ir rinkinių.
Pasirinktinio šaltinio raktas	`kbsrc_…`	Tik savo pasirinktinio šaltinio push operacijos (`/v1/push/sources/{source_id}/…`).
OAuth prieigos žetonas	`kbat_…`	API žinyno operacijos, neperžengiant žetono apimčių. Žetonas, gautas iš `POST /oauth/token` su autorizacijos kodu, veikia sutikimą davusio darbuotojo vardu; `client_credentials` žetonas veikia organizacijos vardu, kaip API raktas. Jis galioja 1 valandą.

Visi jie siunčiami vienodai. Pasirinktinio šaltinio raktas negali nieko skaityti, ieškoti ar keisti už savo šaltinio ribų; naudokite jį ten, kur raktą saugo trečioji šalis, pavyzdžiui, integracijų platforma.

Autentifikavimo klaidos

Būsena ir kodas	Ką tai reiškia	Ką daryti
`401` `auth.not_authenticated`	Rakto nėra, jis įvestas su klaida arba atšauktas.	Patikrinkite antraštę ir rakto reikšmę.
`401` `api_keys.expired`	Rakto galiojimo data praėjo.	Sukurkite naują raktą ir pakeiskite juo senąjį.
`401` `sources.push_key_invalid`	Pasirinktinio šaltinio raktas neteisingas, atšauktas arba priklauso kitam šaltiniui.	Patikrinkite raktą ir šaltinio ID kelyje.
`401` `oauth.token_expired`	OAuth prieigos žetono galiojimas baigėsi.	Gaukite naują su atnaujinimo žetonu.
`403` `api_keys.scope`	Raktas neturi šiai operacijai reikiamos apimties.	Pridėkite apimtį arba naudokite raktą, kuris ją turi.
`403` `api_keys.feature_disabled`	Organizacijos planas neapima API raktų.	Kreipkitės į organizacijos administratorių.
`403` `api_keys.ip_not_allowed`	Užklausa siunčiama iš adreso, kuris nepatenka į rakto leidžiamus adresus.	Kvieskite iš leidžiamo tinklo arba pakeiskite rakto adresus.
`403` `api_keys.mcp_only`	Asmeninis MCP raktas panaudotas ne operacijai `/mcp`.	API kvieskite su organizacijos API raktu.
`403` `oauth.operation_not_allowed`	Operacija nepriklauso viešajai API, todėl OAuth žetonas negali jos kviesti.	Naudokite operaciją iš API žinyno.
`403` `org.suspended`	Organizacijos veikla sustabdyta. Jos duomenys išsaugomi.	Kreipkitės į organizacijos administratorių.

403 reiškia, kad užklausa autentifikuota, bet neleidžiama. Objektui, kurio raktui neleidžiama matyti, grąžinama 404 – taip pat kaip neegzistuojančiam objektui, todėl raktas negali sužinoti, kas yra už jo prieigos ribų.

Veikimas duomenų profilio vardu

Raktas su vaidmeniu admin gali patikrinti, ką matytų kita žmonių grupė: antraštė X-View-As vykdo užklausą duomenų profilio ir, jei reikia, vaidmens vardu.

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

Šiuo režimu užklausos tik skaito: bet koks pakeitimas grąžina 403 su kodu view_as.read_only. OAuth žetonas arba raktas be vaidmens admin negali naudoti X-View-As: grąžinama 403 su kodu view_as.admin_key_required. Antraštei, kuri nenurodo jokio esamo profilio, grąžinama 400 su kodu view_as.invalid_header.

Naršyklės programos

API leidžia užklausas iš bet kokios žiniatinklio kilmės (Access-Control-Allow-Origin: *) ir niekada nenaudoja slapukų, todėl puslapis gali ją kviesti su fetch. Tada raktas yra puslapyje ir jį mato kiekvienas, kas puslapiu naudojasi. Iš naršyklės kvieskite API tik su raktu, kurį sutinkate parodyti tiems naudotojams, pavyzdžiui, raktu viewer, apribotu viešais rinkiniais, arba tarp naršyklės ir Sursos įterpkite savo serverį.

Ką gali tik darbuotojas

Organizacijos API raktas veikia organizacijos, o ne asmens vardu. Dvi API dalys priklauso žmonėms, todėl jos veikia tik su žetonu, kuris veikia darbuotojo vardu: su sesija Sursoje arba su OAuth prieigos žetonu, išduotu darbuotojui sutikus.

Pokalbiai priklauso asmeniui. Organizacijos API raktas GET /v1/conversations mato tik tuos pokalbius, kuriuos pradėjo pats. Viešojoje API nėra operacijos, kuri pradėtų pokalbį, todėl raktui šis sąrašas paprastai tuščias, o darbuotojų pokalbiai jam niekada nerodomi. Klausimai be pokalbio, su POST /v1/ask arba POST /v1/chat, veikia su bet kuriuo raktu, turinčiu apimtį ask. Norėdami gauti darbuotojo pokalbių sąrašą ir perskaityti vieno iš jų istoriją su GET /v1/conversations/{conv_id}, kvieskite API su OAuth žetonu to darbuotojo vardu. Žetonas mato tik paties darbuotojo pokalbius; bet kuriam kitam pokalbiui grąžinama 404 su kodu conversations.not_found.

Kortelę patikrina tik darbuotojas. Tikrinimas patvirtina, kad turinį peržiūrėjo žmogus, todėl POST /v1/cards/{card_id}/verification/verify ir POST /v1/cards/{card_id}/verify reikia sesijos arba OAuth žetono darbuotojo, kuris gali patikrinti kortelę, vardu. Su organizacijos API raktu arba client_credentials žetonu grąžinama 400 su kodu cards.verify_user_account_required. Pirmiausia atliekami įprasti patikrinimai: kortelei, kurios raktas nemato, grąžinama 404, o raktui, kuriam neleidžiama jos patikrinti, grąžinama 403.