Autentifikācija

Katrā Sursa API pieprasījumā galvenē Authorization ir API atslēga vai lietotnes OAuth piekļuves marķieris:

Authorization: Bearer kb_3f9c…

Atslēga identificē organizāciju un nosaka, ko pieprasījums var redzēt un mainīt: tās loma, tvērumi, datu profils un kolekcijas. API adresē nav sesiju un sīkdatņu. Katrs pieprasījums tiek autentificēts atsevišķi, tāpēc ar vienu un to pašu atslēgu varat sūtīt pieprasījumus paralēli un no vairākiem serveriem.

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

Agrākas integrācijas var sūtīt atslēgu galvenē X-API-Key. Tā joprojām tiek pieņemta, bet jaunā kodā izmantojiet Authorization: Bearer.

Akreditācijas datu veidi

Akreditācijas dati	Izskatās	Kur darbojas
Organizācijas API atslēga	`kb_…`	Visas API operācijas atbilstoši tās lomai, tvērumiem, datu profilam un kolekcijām.
Pielāgotā avota atslēga	`kbsrc_…`	Tikai sava pielāgotā avota push operācijas (`/v1/push/sources/{source_id}/…`).
OAuth piekļuves marķieris	`kbat_…`	API rokasgrāmatas operācijas atbilstoši marķiera tvērumiem. Marķieris, kas saņemts no `POST /oauth/token` ar autorizācijas kodu, darbojas tā darbinieka vārdā, kurš devis piekrišanu; `client_credentials` marķieris darbojas organizācijas vārdā, tāpat kā API atslēga. Tas ir derīgs 1 stundu.

Visus šos akreditācijas datus sūta vienādi. Pielāgotā avota atslēga nevar neko lasīt, meklēt vai mainīt ārpus sava avota; izmantojiet to tur, kur atslēgu glabā trešā puse, piemēram, integrāciju platforma.

Autentifikācijas kļūdas

Statuss un kods	Ko tas nozīmē	Kas jādara
`401` `auth.not_authenticated`	Atslēgas nav, tā ievadīta kļūdaini vai ir atsaukta.	Pārbaudiet galveni un atslēgas vērtību.
`401` `api_keys.expired`	Atslēgai beidzies derīguma termiņš.	Izveidojiet jaunu atslēgu un aizstājiet veco.
`401` `sources.push_key_invalid`	Pielāgotā avota atslēga ir nepareiza, atsaukta vai pieder citam avotam.	Pārbaudiet atslēgu un avota ID ceļā.
`401` `oauth.token_expired`	OAuth piekļuves marķierim beidzies derīguma termiņš.	Saņemiet jaunu ar atsvaidzināšanas marķieri.
`403` `api_keys.scope`	Atslēgai nav tvēruma šai operācijai.	Pievienojiet tvērumu vai izmantojiet atslēgu, kurai tas ir.
`403` `api_keys.feature_disabled`	Organizācijas plānā nav iekļautas API atslēgas.	Sazinieties ar organizācijas administratoru.
`403` `api_keys.ip_not_allowed`	Pieprasījums nāk no adreses, kas nav starp atslēgas atļautajām adresēm.	Izsauciet API no atļauta tīkla vai mainiet atslēgas adreses.
`403` `api_keys.mcp_only`	Personīgā MCP atslēga izmantota ārpus operācijas `/mcp`.	API izsaukumiem izmantojiet organizācijas API atslēgu.
`403` `oauth.operation_not_allowed`	Operācija nav daļa no publiskā API, tāpēc OAuth marķieris to nevar izsaukt.	Izmantojiet operāciju no API rokasgrāmatas.
`403` `org.suspended`	Organizācijas darbība ir apturēta. Tās dati tiek saglabāti.	Sazinieties ar organizācijas administratoru.

403 nozīmē, ka pieprasījums ir autentificēts, bet nav atļauts. Pieprasījums pēc objekta, kuru atslēgai nav atļauts redzēt, saņem 404 tāpat kā pēc objekta, kas neeksistē, tāpēc atslēga nevar uzzināt, kas atrodas ārpus tās piekļuves.

Darbība datu profila vārdā

Atslēga ar lomu admin var pārbaudīt, ko redzētu cita cilvēku grupa: galvene X-View-As izpilda pieprasījumu datu profila un, ja vajag, arī lomas vārdā.

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

Šajā režīmā pieprasījumi tikai lasa: jebkura izmaiņa atgriež 403 ar kodu view_as.read_only. OAuth marķieris vai atslēga bez lomas admin nevar izmantot X-View-As: tad atbilde ir 403 ar kodu view_as.admin_key_required. Galvene, kas nenorāda nevienu esošu profilu, saņem 400 ar kodu view_as.invalid_header.

Pārlūka lietotnes

API atļauj pieprasījumus no jebkuras tīmekļa izcelsmes (Access-Control-Allow-Origin: *) un nekad neizmanto sīkdatnes, tāpēc lapa to var izsaukt ar fetch. Tad atslēga atrodas lapā un ir redzama ikvienam, kas lapu izmanto. Izsauciet API no pārlūka tikai ar atslēgu, kuru esat gatavi rādīt šiem lietotājiem, piemēram, viewer atslēgu, kas ierobežota ar publiskām kolekcijām, vai novietojiet savu serveri starp pārlūku un Sursu.

Ko var tikai darbinieks

Organizācijas API atslēga darbojas organizācijas, nevis cilvēka vārdā. Divas API daļas pieder cilvēkiem, tāpēc tās darbojas tikai ar marķieri, kas darbojas darbinieka vārdā: ar sesiju Sursā vai ar OAuth piekļuves marķieri, kas izsniegts ar darbinieka piekrišanu.

Sarunas pieder cilvēkam. Organizācijas API atslēga sarakstā GET /v1/conversations redz tikai tās sarunas, kuras tā sākusi pati. Publiskajā API nav operācijas, kas sāk sarunu, tāpēc atslēgai saraksts parasti ir tukšs, un darbinieku sarunas tai nekad netiek rādītas. Jautājumi bez sarunas ar POST /v1/ask vai POST /v1/chat darbojas ar jebkuru atslēgu, kurai ir tvērums ask. Lai iegūtu darbinieka sarunu sarakstu un nolasītu vienas sarunas vēsturi ar GET /v1/conversations/{conv_id}, izsauciet API ar OAuth marķieri šī darbinieka vārdā. Marķieris redz tikai paša darbinieka sarunas; jebkura cita saruna atgriež 404 ar kodu conversations.not_found.

Kartīti pārbauda tikai darbinieks. Pārbaude apliecina, ka saturu ir pārbaudījis cilvēks, tāpēc operācijām POST /v1/cards/{card_id}/verification/verify un POST /v1/cards/{card_id}/verify ir vajadzīga sesija vai OAuth marķieris tā darbinieka vārdā, kurš drīkst pārbaudīt kartīti. Ar organizācijas API atslēgu vai client_credentials marķieri tās atgriež 400 ar kodu cards.verify_user_account_required. Vispirms notiek parastās pārbaudes: kartīte, ko atslēga nevar redzēt, atgriež 404, bet atslēga, kurai nav atļauts to pārbaudīt, saņem 403.