Autentificering

Hver anmodning til Sursas API har en API-nøgle eller et OAuth-adgangstoken fra en app i headeren Authorization:

Authorization: Bearer kb_3f9c…

Nøglen identificerer organisationen og bestemmer, hvad anmodningen kan se og ændre: nøglens rolle, dens scopes, dens dataprofil og dens samlinger. Der er ingen sessioner eller cookies på API-adressen. Hver anmodning autentificeres for sig, så du kan sende anmodninger parallelt og fra flere servere med den samme nøgle.

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

Tidligere integrationer sender måske nøglen i en X-API-Key-header i stedet. Den accepteres stadig, men ny kode bør bruge Authorization: Bearer.

Typer af legitimationsoplysninger

Legitimation	Ser sådan ud	Hvor den virker
Organisationens API-nøgle	`kb_…`	Alle API’ets operationer inden for nøglens rolle, scopes, dataprofil og samlinger.
Nøgle til en brugerdefineret kilde	`kbsrc_…`	Kun push-operationerne for dens egen brugerdefinerede kilde (`/v1/push/sources/{source_id}/…`).
OAuth-adgangstoken	`kbat_…`	Operationerne i API-referencen inden for tokenets scopes. Et token fra `POST /oauth/token` med en autorisationskode handler på vegne af den medarbejder, der gav samtykke; et `client_credentials`-token handler for organisationen ligesom en API-nøgle. Det er gyldigt i 1 time.

Alle sendes på samme måde. En kildenøgle kan ikke læse, søge i eller ændre noget uden for sin kilde; brug den der, hvor nøglen opbevares af en tredjepart, fx en integrationsplatform.

Autentificeringsfejl

Status og kode	Hvad det betyder	Hvad du gør
`401` `auth.not_authenticated`	Ingen nøgle, en forkert indtastet nøgle eller en tilbagekaldt nøgle.	Kontrollér headeren og nøglens værdi.
`401` `api_keys.expired`	Nøglen har passeret sin udløbsdato.	Opret en ny nøgle, og erstat den gamle.
`401` `sources.push_key_invalid`	En kildenøgle er forkert, tilbagekaldt eller hører til en anden kilde.	Kontrollér nøglen og kildens id i stien.
`401` `oauth.token_expired`	OAuth-adgangstokenet er udløbet.	Hent et nyt med opdateringstokenet.
`403` `api_keys.scope`	Nøglen har intet scope til denne operation.	Tilføj scopet, eller brug en nøgle, der har det.
`403` `api_keys.feature_disabled`	Organisationens prisplan omfatter ikke API-nøgler.	Kontakt organisationens administrator.
`403` `api_keys.ip_not_allowed`	Anmodningen kommer fra en adresse uden for nøglens tilladte adresser.	Kald fra et tilladt netværk, eller ændr nøglens adresser.
`403` `api_keys.mcp_only`	En personlig MCP-nøgle blev brugt uden for operationen `/mcp`.	Brug organisationens API-nøgle til API’et.
`403` `oauth.operation_not_allowed`	Operationen er ikke en del af det offentlige API, så et OAuth-token kan ikke kalde den.	Brug en operation fra API-referencen.
`403` `org.suspended`	Organisationen er suspenderet. Dens data bevares.	Kontakt organisationens administrator.

403 betyder, at anmodningen blev autentificeret, men ikke er tilladt. Et objekt, som nøglen ikke har lov til at se, svarer 404 ligesom et objekt, der ikke findes, så en nøgle ikke kan finde ud af, hvad der ligger uden for dens adgang.

Anmodninger som en dataprofil

En nøgle med rollen admin kan kontrollere, hvad en anden gruppe personer ville se: Headeren X-View-As kører en anmodning 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"

Anmodninger i denne tilstand læser kun: Enhver ændring returnerer 403 med koden view_as.read_only. Et OAuth-token eller en nøgle uden rollen admin kan ikke bruge X-View-As: Anmodningen returnerer 403 med koden view_as.admin_key_required. En header, der ikke angiver en eksisterende profil, returnerer 400 med koden view_as.invalid_header.

Browserapplikationer

API’et tillader anmodninger fra enhver weboprindelse (Access-Control-Allow-Origin: *) og bruger aldrig cookies, så en side kan kalde det med fetch. Nøglen ligger så i siden og er synlig for den, der bruger den. Kald kun API’et fra browseren med en nøgle, som du er villig til at vise disse brugere, fx en viewer-nøgle, der er begrænset til offentlige samlinger, eller sæt din egen server mellem browseren og Sursa.

Hvad kun en medarbejder kan gøre

Organisationens API-nøgle handler for organisationen, ikke for en person. To dele af API’et tilhører personer, så de virker kun med et token, der handler på vegne af en medarbejder: en session i Sursa eller et OAuth-adgangstoken, der er udstedt med medarbejderens samtykke.

Samtaler tilhører en person. Organisationens API-nøgle ser i GET /v1/conversations kun de samtaler, som den selv har startet. Det offentlige API har ingen operation, der starter en samtale, så for en nøgle er listen normalt tom, og medarbejdernes samtaler vises aldrig for den. Spørgsmål uden en samtale med POST /v1/ask eller POST /v1/chat virker med enhver nøgle, der har scopet ask. Vil du vise en medarbejders samtaler og læse historikken for en af dem med GET /v1/conversations/{conv_id}, skal du kalde API’et med et OAuth-token på vegne af den pågældende medarbejder. Tokenet ser kun medarbejderens egne samtaler; enhver anden samtale returnerer 404 med koden conversations.not_found.

Kun en medarbejder verificerer et kort. Verificering bekræfter, at en person har kontrolleret indholdet, så POST /v1/cards/{card_id}/verification/verify og POST /v1/cards/{card_id}/verify kræver en session eller et OAuth-token på vegne af en medarbejder, der må verificere kortet. Med organisationens API-nøgle eller et client_credentials-token returnerer de 400 med koden cards.verify_user_account_required. De sædvanlige kontroller kommer først: Et kort, som nøglen ikke kan se, returnerer 404, og en nøgle, der ikke må verificere det, får 403.