Autenticació

Cada sol·licitud a l’API de Sursa porta una clau d’API, o un token d’accés OAuth d’una aplicació, a la capçalera Authorization:

Authorization: Bearer kb_3f9c…

La clau identifica l’organització i decideix què pot veure i canviar la sol·licitud: el seu rol, els seus àmbits, el seu perfil de dades i les seves col·leccions. A l’adreça de l’API no hi ha sessions ni galetes. Cada sol·licitud s’autentica per separat, de manera que podeu enviar sol·licituds en paral·lel i des de diversos servidors amb la mateixa clau.

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

Les integracions anteriors poden enviar la clau en una capçalera X-API-Key. Encara s’accepta, però el codi nou ha de fer servir Authorization: Bearer.

Tipus de credencials

Credencial	Format	On funciona
Clau d’API de l’organització	`kb_…`	Tots els punts finals de l’API, dins del seu rol, els seus àmbits, el seu perfil de dades i les seves col·leccions.
Clau de la font personalitzada	`kbsrc_…`	Només els punts finals d’enviament de la seva pròpia font personalitzada (`/v1/push/sources/{source_id}/…`).
Token d’accés OAuth	`kbat_…`	Els punts finals de la referència de l’API, dins dels àmbits del token. Un token obtingut amb `POST /oauth/token` a partir d’un codi d’autorització actua en nom de la persona treballadora que ha donat el consentiment; un token `client_credentials` actua per l’organització, com una clau d’API. És vàlid durant 1 hora.

Totes s’envien de la mateixa manera. Una clau de font personalitzada no pot llegir, cercar ni canviar res fora de la seva font; feu-la servir quan la clau l’hagi de guardar un tercer, com ara una plataforma d’integració.

Errors d’autenticació

Estat i codi	Què vol dir	Què cal fer
`401` `auth.not_authenticated`	No hi ha clau, la clau està mal escrita o s’ha revocat.	Comproveu la capçalera i el valor de la clau.
`401` `api_keys.expired`	La clau ha superat la data de caducitat.	Creeu una clau nova i substituïu l’antiga.
`401` `sources.push_key_invalid`	La clau de la font personalitzada és incorrecta, s’ha revocat o pertany a una altra font.	Comproveu la clau i l’ID de la font al camí.
`401` `oauth.token_expired`	El token d’accés OAuth ha caducat.	Obteniu-ne un de nou amb el token d’actualització.
`403` `api_keys.scope`	La clau no té l’àmbit necessari per a aquesta operació.	Afegiu l’àmbit o feu servir una clau que el tingui.
`403` `api_keys.feature_disabled`	El pla de l’organització no inclou claus d’API.	Contacteu amb qui administra l’organització.
`403` `api_keys.ip_not_allowed`	La sol·licitud arriba des d’una adreça que no és entre les adreces permeses de la clau.	Feu la crida des d’una xarxa permesa o canvieu les adreces de la clau.
`403` `api_keys.mcp_only`	S’ha fet servir una clau MCP personal fora del punt final `/mcp`.	Feu servir una clau d’API de l’organització per a l’API.
`403` `oauth.operation_not_allowed`	L’operació no forma part de l’API pública, de manera que un token OAuth no la pot cridar.	Feu servir una operació de la referència de l’API.
`403` `org.suspended`	L’organització està suspesa. Les seves dades es conserven.	Contacteu amb qui administra l’organització.

403 vol dir que la sol·licitud s’ha autenticat però no està permesa. Un objecte que la clau no pot veure respon 404, igual que un objecte que no existeix, de manera que una clau no pot saber què hi ha fora del seu accés.

Actuar com un perfil de dades

Una clau amb el rol admin pot comprovar què veuria un altre grup de persones: la capçalera X-View-As executa una sol·licitud com un perfil de dades i, opcionalment, amb un rol.

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

Les sol·licituds en aquest mode només llegeixen: qualsevol canvi retorna 403 amb el codi view_as.read_only. Un token OAuth, o una clau sense el rol admin, no pot fer servir X-View-As: respon 403 amb el codi view_as.admin_key_required. Una capçalera que no designa cap perfil existent respon 400 amb el codi view_as.invalid_header.

Aplicacions de navegador

L’API admet sol·licituds des de qualsevol origen web (Access-Control-Allow-Origin: *) i no fa servir mai galetes, de manera que una pàgina la pot cridar amb fetch. Aleshores la clau és a la pàgina i la pot veure qui la faci servir. Crideu l’API des del navegador només amb una clau que no us importi mostrar a aquestes persones, com ara una clau viewer limitada a col·leccions públiques, o poseu el vostre propi servidor entre el navegador i Sursa.

Què només pot fer una persona treballadora

Una clau d’API de l’organització actua per l’organització, no per una persona. Dues parts de l’API pertanyen a les persones, de manera que només funcionen amb un token que actuï en nom d’una persona treballadora: una sessió a Sursa o un token d’accés OAuth emès amb el consentiment d’aquesta persona.

Les converses pertanyen a una persona. Una clau d’API de l’organització només veu a GET /v1/conversations les converses que ha iniciat ella mateixa. L’API pública no té cap operació que iniciï una conversa, de manera que per a una clau la llista normalment és buida, i les converses del personal no se li mostren mai. Les preguntes sense conversa, amb POST /v1/ask o POST /v1/chat, funcionen amb qualsevol clau que tingui l’àmbit ask. Per llistar les converses d’una persona treballadora i llegir l’historial d’una d’elles amb GET /v1/conversations/{conv_id}, crideu l’API amb un token OAuth en nom d’aquesta persona. El token només veu les converses pròpies d’aquesta persona; qualsevol altra conversa respon 404 amb el codi conversations.not_found.

Només una persona treballadora verifica una entrada. La verificació confirma que una persona n’ha revisat el contingut, de manera que POST /v1/cards/{card_id}/verification/verify i POST /v1/cards/{card_id}/verify necessiten una sessió o un token OAuth en nom d’una persona treballadora que pugui verificar l’entrada. Amb una clau d’API de l’organització, o amb un token client_credentials, responen 400 amb el codi cards.verify_user_account_required. Primer es fan les comprovacions habituals: una entrada que la clau no pot veure respon 404, i una clau que no té permís per verificar-la respon 403.