Autentimine

Iga Sursa API päring sisaldab päises Authorization API-võtit või rakenduse OAuth-juurdepääsuluba:

Authorization: Bearer kb_3f9c…

Võti tuvastab organisatsiooni ja määrab, mida päring näha ja muuta saab: seda määravad võtme roll, ulatused, andmeprofiil ja kogud. API-aadressil ei ole seansse ega küpsiseid. Iga päring autenditakse eraldi, seega võite saata sama võtmega päringuid paralleelselt ja mitmest serverist.

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

Varasemad integratsioonid võivad saata võtme hoopis päises X-API-Key. Seda aktsepteeritakse endiselt, kuid uues koodis kasutage päist Authorization: Bearer.

Autentimisandmete liigid

Autentimisandmed	Kuju	Kus need toimivad
Organisatsiooni API-võti	`kb_…`	Kõik API lõpp-punktid võtme rolli, ulatuste, andmeprofiili ja kogude piires.
Kohandatud allika võti	`kbsrc_…`	Ainult oma kohandatud allika push-lõpp-punktid (`/v1/push/sources/{source_id}/…`).
OAuth-juurdepääsuluba	`kbat_…`	API teatmiku lõpp-punktid loa ulatuste piires. Autoriseerimiskoodiga lõpp-punktist `POST /oauth/token` saadud luba tegutseb nõusoleku andnud töötaja nimel; loa andmise tüübiga `client_credentials` saadud luba tegutseb organisatsiooni nimel nagu API-võti. Luba kehtib 1 tund.

Kõik need saadetakse ühtemoodi. Kohandatud allika võti ei saa väljaspool oma allikat midagi lugeda, otsida ega muuta; kasutage seda seal, kus võtit hoiab kolmas osapool, näiteks integratsiooniplatvorm.

Autentimisvead

Olek ja kood	Mida see tähendab	Mida teha
`401` `auth.not_authenticated`	Võti puudub, on valesti sisestatud või tühistatud.	Kontrollige päist ja võtme väärtust.
`401` `api_keys.expired`	Võtme aegumiskuupäev on möödunud.	Looge uus võti ja asendage sellega vana.
`401` `sources.push_key_invalid`	Kohandatud allika võti on vale, tühistatud või kuulub teisele allikale.	Kontrollige võtit ja teel olevat allika ID-d.
`401` `oauth.token_expired`	OAuth-juurdepääsuloa kehtivus on lõppenud.	Hankige värskendusloaga uus luba.
`403` `api_keys.scope`	Võtmel ei ole selle toimingu jaoks ulatust.	Lisage ulatus või kasutage võtit, millel see on.
`403` `api_keys.feature_disabled`	Organisatsiooni pakett ei sisalda API-võtmeid.	Pöörduge organisatsiooni administraatori poole.
`403` `api_keys.ip_not_allowed`	Päring tuleb aadressilt, mis ei kuulu võtme lubatud aadresside hulka.	Saatke päring lubatud võrgust või muutke võtme aadresse.
`403` `api_keys.mcp_only`	Isiklikku MCP-võtit kasutati väljaspool lõpp-punkti `/mcp`.	Kasutage API jaoks organisatsiooni API-võtit.
`403` `oauth.operation_not_allowed`	Toiming ei kuulu avalikku API-sse, seega ei saa OAuth-luba seda kutsuda.	Kasutage API teatmikus olevat toimingut.
`403` `org.suspended`	Organisatsiooni tegevus on peatatud. Selle andmed säilitatakse.	Pöörduge organisatsiooni administraatori poole.

403 tähendab, et päring on autenditud, kuid seda ei ole lubatud teha. Objekti puhul, mida võtmel ei ole lubatud näha, tuleb vastus 404 nagu olematu objekti puhul, nii et võti ei saa teada, mis jääb tema juurdepääsust välja.

Tegutsemine andmeprofiili nimel

Rolliga admin võti saab kontrollida, mida näeks mõni teine inimeste rühm: päis X-View-As käivitab päringu andmeprofiili ja soovi korral ka rolli nimel.

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

Selles režiimis päringud ainult loevad: iga muudatus tagastab 403 koodiga view_as.read_only. OAuth-luba ega võti, millel ei ole rolli admin, ei saa päist X-View-As kasutada: vastus on 403 koodiga view_as.admin_key_required. Päis, mis ei nimeta ühtegi olemasolevat profiili, saab vastuse 400 koodiga view_as.invalid_header.

Brauserirakendused

API lubab päringuid mis tahes veebipäritolust (Access-Control-Allow-Origin: *) ega kasuta kunagi küpsiseid, seega saab leht seda kutsuda funktsiooniga fetch. Võti asub siis lehel ja on nähtav igaühele, kes lehte kasutab. Kutsuge API-t brauserist ainult võtmega, mida olete valmis neile kasutajatele näitama, näiteks rolliga viewer võtmega, mis on piiratud avalike kogudega, või pange brauseri ja Sursa vahele oma server.

Mida saab teha ainult töötaja

Organisatsiooni API-võti tegutseb organisatsiooni, mitte inimese nimel. Kaks API osa kuuluvad inimestele, seega toimivad need ainult loaga, mis tegutseb töötaja nimel: Sursa seansiga või töötaja nõusolekul väljastatud OAuth-juurdepääsuloaga.

Vestlused kuuluvad inimesele. Organisatsiooni API-võti näeb lõpp-punktis GET /v1/conversations ainult neid vestlusi, mille ta ise alustas. Avalikus API-s ei ole toimingut, mis vestluse alustaks, seega on võtme jaoks loend tavaliselt tühi ja töötajate vestlusi talle kunagi ei näidata. Küsimused ilma vestluseta, lõpp-punktiga POST /v1/ask või POST /v1/chat, toimivad iga võtmega, millel on ulatus ask. Töötaja vestluste loetlemiseks ja ühe vestluse ajaloo lugemiseks lõpp-punktiga GET /v1/conversations/{conv_id} kutsuge API-t OAuth-loaga selle töötaja nimel. Luba näeb ainult selle töötaja enda vestlusi; iga muu vestluse puhul on vastus 404 koodiga conversations.not_found.

Kaarti kontrollib ainult töötaja. Kontroll kinnitab, et inimene vaatas sisu üle, seega vajavad POST /v1/cards/{card_id}/verification/verify ja POST /v1/cards/{card_id}/verify seanssi või OAuth-luba sellise töötaja nimel, kes tohib kaarti kontrollida. Organisatsiooni API-võtmega või loa andmise tüübiga client_credentials saadud loaga on vastus 400 koodiga cards.verify_user_account_required. Enne seda kontrollitakse nagu tavaliselt juurdepääsu: kaardi puhul, mida võti ei näe, on vastus 404, ja võtmele, millel ei ole lubatud kaarti kontrollida, 403.