Autentisering

Varje anrop till Sursa API bär en API-nyckel, eller en apps OAuth-åtkomsttoken, i huvudet Authorization:

Authorization: Bearer kb_3f9c…

Nyckeln identifierar organisationen och avgör vad anropet kan se och ändra: dess roll, dess omfång, dess dataprofil och dess samlingar. Det finns inga sessioner eller cookies på API-adressen. Varje anrop autentiseras för sig, så du kan skicka anrop parallellt och från flera servrar med samma nyckel.

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

Tidigare integrationer kan i stället skicka nyckeln i huvudet X-API-Key. Det godtas fortfarande, men ny kod bör använda Authorization: Bearer.

Typer av autentiseringsuppgifter

Uppgift	Ser ut som	Var den fungerar
Organisationens API-nyckel	`kb_…`	Varje slutpunkt i API:et, inom nyckelns roll, omfång, dataprofil och samlingar.
Källnyckel	`kbsrc_…`	Bara push-slutpunkterna för den egna källa som nyckeln hör till (`/v1/push/sources/{source_id}/…`).
OAuth-åtkomsttoken	`kbat_…`	Slutpunkterna i API-referensen, inom tokenens omfång. En token från `POST /oauth/token` med en auktoriseringskod agerar för den medarbetare som gav sitt samtycke; en token av typen `client_credentials` agerar för organisationen, som en API-nyckel. Den gäller i 1 timme.

Alla skickas på samma sätt. En källnyckel kan inte läsa, söka eller ändra något utanför sin källa; använd den där nyckeln lagras hos en tredje part, till exempel en integrationsplattform.

Autentiseringsfel

Status och kod	Vad det betyder	Vad du gör
`401` `auth.not_authenticated`	Ingen nyckel, en felskriven nyckel eller en återkallad nyckel.	Kontrollera huvudet och nyckelns värde.
`401` `api_keys.expired`	Nyckeln har passerat sitt utgångsdatum.	Skapa en ny nyckel och ersätt den gamla.
`401` `sources.push_key_invalid`	En källnyckel är fel, återkallad eller hör till en annan källa.	Kontrollera nyckeln och källans id i sökvägen.
`401` `oauth.token_expired`	OAuth-åtkomsttokenen har gått ut.	Hämta en ny med uppdateringstokenen.
`403` `api_keys.scope`	Nyckeln har inget omfång för den här åtgärden.	Lägg till omfånget eller använd en nyckel som har det.
`403` `api_keys.feature_disabled`	Organisationens prisplan omfattar inte API-nycklar.	Kontakta organisationens administratör.
`403` `api_keys.ip_not_allowed`	Anropet kommer från en adress utanför nyckelns tillåtna adresser.	Anropa från ett tillåtet nätverk eller ändra nyckelns adresser.
`403` `api_keys.mcp_only`	En personlig MCP-nyckel användes utanför slutpunkten `/mcp`.	Använd organisationens API-nyckel för API:et.
`403` `oauth.operation_not_allowed`	Åtgärden ingår inte i det offentliga API:et, så en OAuth-token kan inte anropa den.	Använd en åtgärd från API-referensen.
`403` `org.suspended`	Organisationen är avstängd. Dess data finns kvar.	Kontakta organisationens administratör.

403 betyder att anropet autentiserades men inte är tillåtet. Ett objekt som nyckeln inte får se svarar 404, precis som ett objekt som inte finns, så att en nyckel inte kan ta reda på vad som ligger utanför dess åtkomst.

Agera som en dataprofil

En nyckel med rollen admin kan kontrollera vad en annan grupp av personer skulle se: huvudet X-View-As kör ett anrop som en dataprofil och, om du vill, en roll.

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

Anrop i det här läget kan bara läsa: varje ändring returnerar 403 med koden view_as.read_only. En OAuth-token, eller en nyckel utan rollen admin, kan inte använda X-View-As: svaret blir 403 med koden view_as.admin_key_required. Ett huvud som inte anger någon befintlig profil ger svaret 400 med koden view_as.invalid_header.

Webbläsarprogram

API:et tillåter anrop från alla webbursprung (Access-Control-Allow-Origin: *) och använder aldrig cookies, så en sida kan anropa det med fetch. Nyckeln finns då i sidan och syns för den som använder den. Anropa API:et från webbläsaren bara med en nyckel som du är beredd att visa för de användarna, till exempel en viewer-nyckel som är begränsad till offentliga samlingar, eller placera din egen server mellan webbläsaren och Sursa.

Vad bara en medarbetare kan göra

Organisationens API-nyckel agerar för organisationen, inte för en person. Två delar av API:et hör till personer, så de fungerar bara med en token som agerar för en medarbetares räkning: en session i Sursa eller en OAuth-åtkomsttoken som har utfärdats med medarbetarens samtycke.

Konversationer hör till en person. Organisationens API-nyckel ser i GET /v1/conversations bara de konversationer som den själv har startat. Det offentliga API:et har ingen åtgärd som startar en konversation, så för en nyckel är listan normalt tom, och medarbetarnas konversationer visas aldrig för den. Frågor utan konversation, med POST /v1/ask eller POST /v1/chat, fungerar med varje nyckel som har omfånget ask. Om du vill lista en medarbetares konversationer och läsa historiken för en av dem med GET /v1/conversations/{conv_id} anropar du API:et med en OAuth-token för den medarbetarens räkning. Tokenen ser bara medarbetarens egna konversationer; varje annan konversation ger svaret 404 med koden conversations.not_found.

Bara en medarbetare verifierar ett kort. En verifiering bekräftar att en person har kontrollerat innehållet, så POST /v1/cards/{card_id}/verification/verify och POST /v1/cards/{card_id}/verify kräver en session eller en OAuth-token som agerar för en medarbetare som får verifiera kortet. Med organisationens API-nyckel, eller en token av typen client_credentials, blir svaret 400 med koden cards.verify_user_account_required. De vanliga kontrollerna kommer först: ett kort som nyckeln inte kan se ger svaret 404, och en nyckel som inte får verifiera det ger svaret 403.