Hitelesítés

A Sursa API-hoz küldött minden kérés egy API-kulcsot vagy egy alkalmazás OAuth-hozzáférési tokenjét viszi magával az Authorization fejlécben:

Authorization: Bearer kb_3f9c…

A kulcs azonosítja a szervezetet, és eldönti, mit láthat és mit módosíthat a kérés: a szerepköre, a hatókörei, az adatprofilja és a gyűjteményei alapján. Az API-címen nincsenek munkamenetek és sütik. Minden kérés önállóan hitelesül, így ugyanazzal a kulccsal párhuzamosan és több szerverről is küldhetsz kéréseket.

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

A korábbi integrációk a kulcsot X-API-Key fejlécben is küldhetik. Ezt a Sursa továbbra is elfogadja, de az új kód az Authorization: Bearer fejlécet használja.

A hitelesítő adatok fajtái

Hitelesítő adat	Formája	Hol működik
A szervezet API-kulcsa	`kb_…`	Az API minden végpontján, a szerepköre, a hatókörei, az adatprofilja és a gyűjteményei keretein belül.
Az egyéni forrás kulcsa	`kbsrc_…`	Csak a saját egyéni forrásának küldési (push) végpontjain (`/v1/push/sources/{source_id}/…`).
OAuth-hozzáférési token	`kbat_…`	Az API-referencia végpontjain, a token hatókörei keretein belül. Az engedélyezési kóddal a `POST /oauth/token` végponttól kapott token annak a munkatársnak a nevében jár el, aki a hozzájárulását adta; a `client_credentials` token a szervezet nevében jár el, mint egy API-kulcs. 1 óráig érvényes.

Mindegyiket ugyanúgy kell elküldeni. Az egyéni forrás kulcsa a forrásán kívül semmit nem olvashat, nem kereshet és nem módosíthat; ott használd, ahol a kulcsot harmadik fél tárolja, például egy integrációs platform.

Hitelesítési hibák

Állapotkód és hibakód	Mit jelent	Mit tegyél
`401` `auth.not_authenticated`	Nincs kulcs, a kulcs elírt, vagy visszavonták.	Ellenőrizd a fejlécet és a kulcs értékét.
`401` `api_keys.expired`	A kulcs lejárati ideje elmúlt.	Hozz létre új kulcsot, és cseréld le vele a régit.
`401` `sources.push_key_invalid`	Az egyéni forrás kulcsa hibás, visszavonták, vagy egy másik forráshoz tartozik.	Ellenőrizd a kulcsot és az útvonalban szereplő forrásazonosítót.
`401` `oauth.token_expired`	Az OAuth-hozzáférési token lejárt.	Kérj újat a frissítési tokennel.
`403` `api_keys.scope`	A kulcsnak nincs hatóköre ehhez a művelethez.	Add hozzá a hatókört, vagy használj olyan kulcsot, amelynek megvan.
`403` `api_keys.feature_disabled`	A szervezet csomagja nem tartalmaz API-kulcsokat.	Fordulj a szervezet adminisztrátorához.
`403` `api_keys.ip_not_allowed`	A kérés a kulcs engedélyezett címein kívüli címről érkezik.	Engedélyezett hálózatból hívd az API-t, vagy módosítsd a kulcs címeit.
`403` `api_keys.mcp_only`	Személyes MCP-kulcsot használtak a `/mcp` végponton kívül.	Az API-hoz a szervezet API-kulcsát használd.
`403` `oauth.operation_not_allowed`	A művelet nem része a nyilvános API-nak, ezért OAuth-token nem hívhatja.	Az API-referencia egyik műveletét használd.
`403` `org.suspended`	A szervezet fel van függesztve. Az adatai megmaradnak.	Fordulj a szervezet adminisztrátorához.

A 403 azt jelenti, hogy a kérés hitelesítése sikerült, de a kérés nem engedélyezett. Ha a kulcs nem láthat egy objektumot, a válasz 404, ugyanúgy, mint egy nem létező objektumnál, így a kulcs nem tudhatja meg, mi van a hozzáférésén kívül.

Eljárás egy adatprofil nevében

Az admin szerepkörű kulcs ellenőrizheti, mit látna a felhasználók egy másik csoportja: az X-View-As fejléc egy adatprofil és opcionálisan egy szerepkör nevében futtatja a kérést.

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

Az ebben a módban küldött kérések csak olvasnak: bármilyen módosításra a válasz 403 a view_as.read_only kóddal. OAuth-token és admin szerepkör nélküli kulcs nem használhatja az X-View-As fejlécet: a válasz 403 a view_as.admin_key_required kóddal. Ha a fejléc nem létező profilt nevez meg, a válasz 400 a view_as.invalid_header kóddal.

Böngészős alkalmazások

Az API bármilyen webes eredetből fogad kéréseket (Access-Control-Allow-Origin: *), és soha nem használ sütiket, így egy weboldal fetch hívással is elérheti. Ilyenkor a kulcs az oldalon van, és bárki láthatja, aki az oldalt használja. A böngészőből csak olyan kulccsal hívd az API-t, amelyet hajlandó vagy megmutatni ezeknek a felhasználóknak, például egy nyilvános gyűjteményekre korlátozott viewer kulccsal, vagy állíts a böngésző és a Sursa közé saját szervert.

Amit csak egy munkatárs tehet meg

A szervezet API-kulcsa a szervezet nevében jár el, nem egy személyében. Az API két része személyekhez tartozik, ezért csak olyan tokennel működik, amely egy munkatárs nevében jár el: egy Sursában nyitott munkamenettel vagy a munkatárs hozzájárulásával kiadott OAuth-hozzáférési tokennel.

A beszélgetések személyekhez tartoznak. A szervezet API-kulcsa a GET /v1/conversations válaszában csak azokat a beszélgetéseket látja, amelyeket ő maga indított. A nyilvános API-ban nincs beszélgetést indító művelet, ezért egy kulcs számára a lista általában üres, a munkatársak beszélgetései pedig soha nem jelennek meg neki. A beszélgetés nélküli kérdések a POST /v1/ask vagy a POST /v1/chat végponttal bármely olyan kulccsal működnek, amelynek megvan az ask hatóköre. Egy munkatárs beszélgetéseinek listázásához és egy beszélgetés előzményeinek olvasásához a GET /v1/conversations/{conv_id} végponttal az adott munkatárs nevében kiadott OAuth-tokennel hívd az API-t. A token csak a munkatárs saját beszélgetéseit látja; bármely más beszélgetésre a válasz 404 a conversations.not_found kóddal.

Kártyát csak munkatárs ellenőrizhet. Az ellenőrzés azt erősíti meg, hogy egy személy átnézte a tartalmat, ezért a POST /v1/cards/{card_id}/verification/verify és a POST /v1/cards/{card_id}/verify végponthoz munkamenet vagy olyan munkatárs nevében kiadott OAuth-token kell, aki ellenőrizheti a kártyát. A szervezet API-kulcsával vagy client_credentials tokennel a válasz 400 a cards.verify_user_account_required kóddal. A szokásos vizsgálatok előbb futnak le: a kulcs számára nem látható kártyára a válasz 404, és ha a kulcs nem ellenőrizheti a kártyát, a válasz 403.