Autentificare

Fiecare cerere către API-ul Sursa poartă o cheie API sau un token de acces OAuth al unei aplicații în antetul Authorization:

Authorization: Bearer kb_3f9c…

Cheia identifică organizația și decide ce poate vedea și modifica cererea: rolul ei, domeniile ei de acces, profilul ei de date și colecțiile ei. La adresa API nu există sesiuni sau cookie-uri. Fiecare cerere este autentificată separat, așa că puteți trimite cereri în paralel și de pe mai multe servere cu aceeași cheie.

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

Integrările mai vechi pot trimite cheia în antetul X-API-Key. Acesta este acceptat în continuare, dar codul nou ar trebui să folosească Authorization: Bearer.

Tipuri de date de autentificare

Date de autentificare	Arată ca	Unde funcționează
Cheia API a organizației	`kb_…`	Fiecare endpoint al API-ului, în limitele rolului, domeniilor de acces, profilului de date și colecțiilor ei.
Cheie de sursă personalizată	`kbsrc_…`	Doar endpointurile de trimitere (push) ale propriei surse personalizate (`/v1/push/sources/{source_id}/…`).
Token de acces OAuth	`kbat_…`	Endpointurile din referința API, în limitele domeniilor de acces ale tokenului. Un token obținut de la `POST /oauth/token` cu un cod de autorizare acționează în numele angajatului care și-a dat consimțământul; un token `client_credentials` acționează pentru organizație, ca o cheie API. Este valabil o oră.

Toate se trimit la fel. O cheie de sursă personalizată nu poate citi, căuta sau modifica nimic în afara sursei ei; folosiți-o acolo unde cheia este stocată de un terț, de exemplu de o platformă de integrare.

Erori de autentificare

Status și cod	Ce înseamnă	Ce trebuie făcut
`401` `auth.not_authenticated`	Lipsește cheia, cheia este scrisă greșit sau a fost revocată.	Verificați antetul și valoarea cheii.
`401` `api_keys.expired`	Cheia a depășit data de expirare.	Creați o cheie nouă și înlocuiți-o pe cea veche.
`401` `sources.push_key_invalid`	O cheie de sursă personalizată este greșită, revocată sau aparține altei surse.	Verificați cheia și identificatorul sursei din cale.
`401` `oauth.token_expired`	Tokenul de acces OAuth a expirat.	Obțineți unul nou cu tokenul de reîmprospătare.
`403` `api_keys.scope`	Cheia nu are un domeniu de acces pentru această operație.	Adăugați domeniul sau folosiți o cheie care îl are.
`403` `api_keys.feature_disabled`	Planul organizației nu include chei API.	Contactați administratorul organizației.
`403` `api_keys.ip_not_allowed`	Cererea vine de la o adresă din afara adreselor permise ale cheii.	Faceți apelul dintr-o rețea permisă sau modificați adresele cheii.
`403` `api_keys.mcp_only`	O cheie MCP personală a fost folosită în afara endpointului `/mcp`.	Folosiți o cheie API a organizației pentru API.
`403` `oauth.operation_not_allowed`	Operația nu face parte din API-ul public, așa că un token OAuth nu o poate apela.	Folosiți o operație din referința API.
`403` `org.suspended`	Organizația este suspendată. Datele ei sunt păstrate.	Contactați administratorul organizației.

403 înseamnă că cererea a fost autentificată, dar nu este permisă. Pentru un obiect pe care cheia nu are voie să-l vadă, răspunsul este 404, la fel ca pentru un obiect care nu există, așa că o cheie nu poate afla ce se află în afara accesului ei.

Acțiunea cu un profil de date

O cheie cu rolul admin poate verifica ce ar vedea un alt grup de persoane: antetul X-View-As execută o cerere cu un profil de date și, opțional, cu un rol.

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

Cererile în acest mod doar citesc: orice modificare returnează 403 cu codul view_as.read_only. Un token OAuth sau o cheie fără rolul admin nu poate folosi X-View-As: răspunsul este 403 cu codul view_as.admin_key_required. Un antet care nu numește niciun profil existent primește răspunsul 400 cu codul view_as.invalid_header.

Aplicații în browser

API-ul acceptă cereri de la orice origine web (Access-Control-Allow-Origin: *) și nu folosește niciodată cookie-uri, așa că o pagină îl poate apela cu fetch. Cheia se află atunci în pagină și este vizibilă pentru oricine o folosește. Apelați API-ul din browser doar cu o cheie pe care sunteți dispuși să o arătați acestor utilizatori, de exemplu o cheie viewer limitată la colecțiile publice, sau puneți propriul server între browser și Sursa.

Ce poate face doar un angajat

O cheie API a organizației acționează pentru organizație, nu pentru o persoană. Două părți ale API-ului aparțin persoanelor, așa că funcționează doar cu un token care acționează în numele unui angajat: o sesiune în Sursa sau un token de acces OAuth emis cu consimțământul angajatului.

Conversațiile aparțin unei persoane. O cheie API a organizației vede în GET /v1/conversations doar conversațiile pe care le-a început ea însăși. API-ul public nu are nicio operație care începe o conversație, așa că pentru o cheie lista este de regulă goală, iar conversațiile angajaților nu îi sunt niciodată arătate. Întrebările fără conversație, cu POST /v1/ask sau POST /v1/chat, funcționează cu orice cheie care are domeniul ask. Pentru a enumera conversațiile unui angajat și a citi istoricul uneia dintre ele cu GET /v1/conversations/{conv_id}, apelați API-ul cu un token OAuth în numele acelui angajat. Tokenul vede doar conversațiile proprii ale angajatului; orice altă conversație primește răspunsul 404 cu codul conversations.not_found.

Doar un angajat verifică o fișă. Verificarea confirmă că o persoană a controlat conținutul, de aceea POST /v1/cards/{card_id}/verification/verify și POST /v1/cards/{card_id}/verify necesită o sesiune sau un token OAuth în numele unui angajat care are dreptul să verifice fișa. Cu o cheie API a organizației sau cu un token client_credentials, ele răspund 400 cu codul cards.verify_user_account_required. Verificările obișnuite au loc mai întâi: o fișă pe care cheia nu o poate vedea primește răspunsul 404, iar o cheie care nu are dreptul să o verifice primește 403.