Autentisering

Hver forespørsel til Sursas API har en API-nøkkel, eller et OAuth-tilgangstoken fra en applikasjon, i headeren Authorization:

Authorization: Bearer kb_3f9c…

Nøkkelen identifiserer organisasjonen og avgjør hva forespørselen kan se og endre: rollen, scopene, dataprofilen og samlingene til nøkkelen. Det finnes ingen økter eller informasjonskapsler på API-adressen. Hver forespørsel autentiseres for seg, så du kan sende forespørsler parallelt og fra flere servere med samme nøkkel.

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

Tidligere integrasjoner kan sende nøkkelen i en X-API-Key-header i stedet. Den godtas fortsatt, men ny kode bør bruke Authorization: Bearer.

Typer påloggingsinformasjon

Påloggingsinformasjon	Ser slik ut	Hvor den virker
Organisasjonens API-nøkkel	`kb_…`	Alle operasjoner i API-et, innenfor rollen, scopene, dataprofilen og samlingene til nøkkelen.
Nøkkel for en egendefinert kilde	`kbsrc_…`	Bare push-operasjonene til dens egen egendefinerte kilde (`/v1/push/sources/{source_id}/…`).
OAuth-tilgangstoken	`kbat_…`	Operasjonene i API-referansen, innenfor scopene til tokenet. Et token fra `POST /oauth/token` med en autorisasjonskode opptrer på vegne av den ansatte som ga samtykke; et `client_credentials`-token opptrer for organisasjonen, som en API-nøkkel. Det er gyldig i 1 time.

Alle sendes på samme måte. En kildenøkkel kan ikke lese, søke i eller endre noe utenfor kilden sin; bruk den der nøkkelen lagres hos en tredjepart, for eksempel en integrasjonsplattform.

Autentiseringsfeil

Status og kode	Hva det betyr	Hva du gjør
`401` `auth.not_authenticated`	Ingen nøkkel, en feilskrevet nøkkel eller en tilbaketrukket nøkkel.	Kontroller headeren og verdien til nøkkelen.
`401` `api_keys.expired`	Nøkkelen har passert utløpsdatoen.	Opprett en ny nøkkel, og erstatt den gamle.
`401` `sources.push_key_invalid`	En kildenøkkel er feil, tilbaketrukket eller tilhører en annen kilde.	Kontroller nøkkelen og kildens ID i banen.
`401` `oauth.token_expired`	OAuth-tilgangstokenet er utløpt.	Hent et nytt med oppdateringstokenet.
`403` `api_keys.scope`	Nøkkelen mangler scope for denne operasjonen.	Legg til scopet, eller bruk en nøkkel som har det.
`403` `api_keys.feature_disabled`	Organisasjonens prisplan omfatter ikke API-nøkler.	Kontakt administratoren for organisasjonen.
`403` `api_keys.ip_not_allowed`	Forespørselen kommer fra en adresse utenfor nøkkelens tillatte adresser.	Kall fra et tillatt nettverk, eller endre adressene til nøkkelen.
`403` `api_keys.mcp_only`	En personlig MCP-nøkkel ble brukt utenfor operasjonen `/mcp`.	Bruk organisasjonens API-nøkkel til API-et.
`403` `oauth.operation_not_allowed`	Operasjonen er ikke en del av det offentlige API-et, så et OAuth-token kan ikke kalle den.	Bruk en operasjon fra API-referansen.
`403` `org.suspended`	Organisasjonen er suspendert. Dataene er tatt vare på.	Kontakt administratoren for organisasjonen.

403 betyr at forespørselen er autentisert, men ikke tillatt. Et objekt som nøkkelen ikke har lov til å se, svarer 404, akkurat som et objekt som ikke finnes, så en nøkkel kan ikke finne ut hva som ligger utenfor tilgangen dens.

Opptre som en dataprofil

En nøkkel med rollen admin kan kontrollere hva en annen gruppe personer ville se: Headeren X-View-As kjører en forespørsel som en dataprofil og eventuelt som en rolle.

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

Forespørsler i denne modusen leser bare: Enhver endring returnerer 403 med koden view_as.read_only. Et OAuth-token, eller en nøkkel uten rollen admin, kan ikke bruke X-View-As: Da svarer API-et 403 med koden view_as.admin_key_required. En header som ikke peker på noen eksisterende profil, svarer 400 med koden view_as.invalid_header.

Nettleserapplikasjoner

API-et tillater forespørsler fra alle nettopprinnelser (Access-Control-Allow-Origin: *) og bruker aldri informasjonskapsler, så en side kan kalle det med fetch. Nøkkelen ligger da i siden og er synlig for alle som bruker den. Kall API-et fra nettleseren bare med en nøkkel du er villig til å vise disse brukerne, for eksempel en viewer-nøkkel som er begrenset til offentlige samlinger, eller sett din egen server mellom nettleseren og Sursa.

Hva bare en ansatt kan gjøre

Organisasjonens API-nøkkel opptrer for organisasjonen, ikke for en person. To deler av API-et tilhører personer, så de virker bare med et token som opptrer på vegne av en ansatt: en økt i Sursa eller et OAuth-tilgangstoken som er utstedt med samtykke fra den ansatte.

Samtaler tilhører en person. Organisasjonens API-nøkkel ser i GET /v1/conversations bare samtalene den har startet selv. Det offentlige API-et har ingen operasjon som starter en samtale, så for en nøkkel er listen normalt tom, og samtalene til de ansatte vises aldri for den. Spørsmål uten samtale, med POST /v1/ask eller POST /v1/chat, virker med alle nøkler som har scopet ask. For å vise samtalene til en ansatt og lese historikken i en av dem med GET /v1/conversations/{conv_id} kaller du API-et med et OAuth-token på vegne av den ansatte. Tokenet ser bare den ansattes egne samtaler; alle andre samtaler svarer 404 med koden conversations.not_found.

Bare en ansatt verifiserer et kort. Verifisering bekrefter at en person har kontrollert innholdet, så POST /v1/cards/{card_id}/verification/verify og POST /v1/cards/{card_id}/verify krever en økt eller et OAuth-token på vegne av en ansatt som har lov til å verifisere kortet. Med organisasjonens API-nøkkel, eller et client_credentials-token, svarer de 400 med koden cards.verify_user_account_required. De vanlige kontrollene kommer først: Et kort som nøkkelen ikke kan se, svarer 404, og en nøkkel som ikke har lov til å verifisere det, svarer 403.