Authenticatie

Elk request aan de Sursa API bevat een API-sleutel, of een OAuth-toegangstoken van een app, in de header Authorization:

Authorization: Bearer kb_3f9c…

De sleutel identificeert de organisatie en bepaalt wat het request kan zien en wijzigen: zijn rol, zijn scopes, zijn dataprofiel en zijn collecties. Op het API-adres zijn er geen sessies of cookies. Elk request wordt afzonderlijk geauthenticeerd, dus je kunt met dezelfde sleutel requests parallel en vanaf meerdere servers versturen.

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

Eerdere integraties sturen de sleutel soms in een header X-API-Key. Die wordt nog steeds geaccepteerd, maar nieuwe code gebruikt beter Authorization: Bearer.

Soorten authenticatiegegevens

Gegeven	Ziet eruit als	Waar het werkt
API-sleutel van de organisatie	`kb_…`	Elk endpoint van de API, binnen de rol, scopes, het dataprofiel en de collecties van de sleutel.
Bronsleutel	`kbsrc_…`	Alleen de push-endpoints van de eigen bron waar hij bij hoort (`/v1/push/sources/{source_id}/…`).
OAuth-toegangstoken	`kbat_…`	De endpoints van de API-referentie, binnen de scopes van het token. Een token van `POST /oauth/token` met een autorisatiecode treedt op namens de medewerker die toestemming heeft gegeven; een `client_credentials`-token treedt op voor de organisatie, net als een API-sleutel. Het is 1 uur geldig.

Ze worden allemaal op dezelfde manier meegestuurd. Een bronsleutel kan niets lezen, zoeken of wijzigen buiten zijn bron; gebruik hem waar de sleutel door een derde partij wordt bewaard, zoals een integratieplatform.

Authenticatiefouten

Status en code	Wat het betekent	Wat je doet
`401` `auth.not_authenticated`	Geen sleutel, een verkeerd getypte sleutel of een ingetrokken sleutel.	Controleer de header en de waarde van de sleutel.
`401` `api_keys.expired`	De verloopdatum van de sleutel is verstreken.	Maak een nieuwe sleutel en vervang de oude.
`401` `sources.push_key_invalid`	Een bronsleutel is onjuist, ingetrokken of hoort bij een andere bron.	Controleer de sleutel en de ID van de bron in het pad.
`401` `oauth.token_expired`	Het OAuth-toegangstoken is verlopen.	Haal met het vernieuwingstoken een nieuw token op.
`403` `api_keys.scope`	De sleutel heeft geen scope voor deze bewerking.	Voeg de scope toe of gebruik een sleutel die hem heeft.
`403` `api_keys.feature_disabled`	Het abonnement van de organisatie omvat geen API-sleutels.	Neem contact op met de beheerder van de organisatie.
`403` `api_keys.ip_not_allowed`	Het request komt van een adres buiten de toegestane adressen van de sleutel.	Roep de API aan vanuit een toegestaan netwerk of wijzig de adressen van de sleutel.
`403` `api_keys.mcp_only`	Een persoonlijke MCP-sleutel is gebruikt buiten het endpoint `/mcp`.	Gebruik voor de API een API-sleutel van de organisatie.
`403` `oauth.operation_not_allowed`	De bewerking hoort niet bij de openbare API, dus een OAuth-token kan haar niet aanroepen.	Gebruik een bewerking uit de API-referentie.
`403` `org.suspended`	De organisatie is opgeschort. De gegevens blijven bewaard.	Neem contact op met de beheerder van de organisatie.

403 betekent dat het request is geauthenticeerd, maar niet is toegestaan. Een object dat de sleutel niet mag zien, geeft 404, net als een object dat niet bestaat, zodat een sleutel niet te weten kan komen wat buiten zijn toegang ligt.

Optreden als dataprofiel

Een sleutel met de rol admin kan controleren wat een andere groep mensen zou zien: de header X-View-As voert een request uit als een dataprofiel en, optioneel, met een rol.

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

Requests in deze modus lezen alleen: elke wijziging geeft 403 met de code view_as.read_only. Een OAuth-token, of een sleutel zonder de rol admin, kan X-View-As niet gebruiken: dat geeft 403 met de code view_as.admin_key_required. Een header die geen bestaand profiel noemt, geeft 400 met de code view_as.invalid_header.

Browserapplicaties

De API staat requests toe vanaf elke web-origin (Access-Control-Allow-Origin: *) en gebruikt nooit cookies, dus een pagina kan hem aanroepen met fetch. De sleutel staat dan in de pagina en is zichtbaar voor iedereen die de pagina gebruikt. Roep de API vanuit de browser alleen aan met een sleutel die je aan die gebruikers wilt laten zien, zoals een viewer-sleutel die beperkt is tot openbare collecties, of zet je eigen server tussen de browser en Sursa.

Wat alleen een medewerker kan doen

Een API-sleutel van de organisatie treedt op voor de organisatie, niet voor een persoon. Twee delen van de API horen bij mensen, dus ze werken alleen met een token dat namens een medewerker optreedt: een sessie in Sursa of een OAuth-toegangstoken dat met toestemming van de medewerker is uitgegeven.

Gesprekken horen bij een persoon. Een API-sleutel van de organisatie ziet in GET /v1/conversations alleen de gesprekken die hij zelf heeft gestart. De openbare API heeft geen bewerking die een gesprek start, dus voor een sleutel is de lijst normaal gesproken leeg, en de gesprekken van medewerkers krijgt hij nooit te zien. Vragen zonder gesprek, met POST /v1/ask of POST /v1/chat, werken met elke sleutel die de scope ask heeft. Wil je de gesprekken van een medewerker weergeven en de geschiedenis van een gesprek lezen met GET /v1/conversations/{conv_id}, roep de API dan aan met een OAuth-token namens die medewerker. Het token ziet alleen de eigen gesprekken van die medewerker; elk ander gesprek geeft 404 met de code conversations.not_found.

Alleen een medewerker verifieert een kaart. Verificatie bevestigt dat een persoon de inhoud heeft gecontroleerd, dus POST /v1/cards/{card_id}/verification/verify en POST /v1/cards/{card_id}/verify vereisen een sessie of een OAuth-token namens een medewerker die de kaart mag verifiëren. Met een API-sleutel van de organisatie of een client_credentials-token geven ze 400 met de code cards.verify_user_account_required. Eerst komen de gebruikelijke controles: een kaart die de sleutel niet kan zien, geeft 404, en een sleutel die de kaart niet mag verifiëren, krijgt 403.