Todennus

Jokaisessa Sursa API:n pyynnössä on Authorization-otsakkeessa API-avain tai sovelluksen OAuth-käyttöoikeustunnus:

Authorization: Bearer kb_3f9c…

Avain tunnistaa organisaation ja ratkaisee, mitä pyyntö voi nähdä ja muuttaa: sen rooli, sen käyttöalueet, sen dataprofiili ja sen kokoelmat. API-osoitteessa ei ole istuntoja eikä evästeitä. Jokainen pyyntö todennetaan erikseen, joten voit lähettää pyyntöjä samalla avaimella rinnakkain ja useilta palvelimilta.

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

Aiemmat integraatiot voivat lähettää avaimen sen sijaan X-API-Key-otsakkeessa. Se hyväksytään edelleen, mutta uudessa koodissa kannattaa käyttää Authorization: Bearer -muotoa.

Tunnistetietojen lajit

Tunnistetieto	Muoto	Missä se toimii
Organisaation API-avain	`kb_…`	Kaikki API:n päätepisteet avaimen roolin, käyttöalueiden, dataprofiilin ja kokoelmien rajoissa.
Mukautetun lähteen avain	`kbsrc_…`	Vain oman mukautetun lähteensä push-päätepisteet (`/v1/push/sources/{source_id}/…`).
OAuth-käyttöoikeustunnus	`kbat_…`	API-viitteen päätepisteet käyttöoikeustunnuksen käyttöalueiden rajoissa. Valtuutuskoodilla `POST /oauth/token` -päätepisteestä saatu käyttöoikeustunnus toimii sen työntekijän puolesta, joka antoi suostumuksen; `client_credentials`-käyttöoikeustunnus toimii organisaation puolesta kuten API-avain. Käyttöoikeustunnus on voimassa 1 tunnin.

Kaikki lähetetään samalla tavalla. Mukautetun lähteen avain ei voi lukea, hakea eikä muuttaa mitään lähteensä ulkopuolella; käytä sitä silloin, kun avainta säilyttää kolmas osapuoli, kuten integraatioalusta.

Todennusvirheet

Tila ja koodi	Mitä se tarkoittaa	Mitä tehdä
`401` `auth.not_authenticated`	Avain puuttuu, se on kirjoitettu väärin tai se on peruttu.	Tarkista otsake ja avaimen arvo.
`401` `api_keys.expired`	Avaimen vanhenemispäivä on ohitettu.	Luo uusi avain ja korvaa vanha sillä.
`401` `sources.push_key_invalid`	Mukautetun lähteen avain on väärä tai peruttu, tai se kuuluu toiselle lähteelle.	Tarkista avain ja polussa oleva lähteen tunnus.
`401` `oauth.token_expired`	OAuth-käyttöoikeustunnuksen voimassaolo on päättynyt.	Hae uusi käyttöoikeustunnus päivitystunnuksella.
`403` `api_keys.scope`	Avaimella ei ole tämän toiminnon käyttöaluetta.	Lisää käyttöalue tai käytä avainta, jolla se on.
`403` `api_keys.feature_disabled`	Organisaation pakettiin eivät sisälly API-avaimet.	Ota yhteyttä organisaation ylläpitäjään.
`403` `api_keys.ip_not_allowed`	Pyyntö tulee osoitteesta, joka ei kuulu avaimen sallittuihin osoitteisiin.	Kutsu API:a sallitusta verkosta tai muuta avaimen osoitteita.
`403` `api_keys.mcp_only`	Henkilökohtaista MCP-avainta käytettiin `/mcp`-päätepisteen ulkopuolella.	Käytä API:ssa organisaation API-avainta.
`403` `oauth.operation_not_allowed`	Toiminto ei ole osa julkista API:a, joten OAuth-käyttöoikeustunnus ei voi kutsua sitä.	Käytä API-viitteessä kuvattua toimintoa.
`403` `org.suspended`	Organisaation toiminta on keskeytetty. Sen tiedot säilytetään.	Ota yhteyttä organisaation ylläpitäjään.

403 tarkoittaa, että pyyntö on todennettu, mutta sitä ei sallita. Objekti, jota avain ei saa nähdä, vastaa 404 aivan kuten objekti, jota ei ole olemassa, joten avain ei voi saada selville, mitä sen käyttöoikeuksien ulkopuolella on.

Toimiminen dataprofiilin puolesta

Avain, jolla on rooli admin, voi tarkistaa, mitä jokin toinen ihmisryhmä näkisi: X-View-As-otsake suorittaa pyynnön dataprofiilin ja valinnaisesti myös roolin puolesta.

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

Tässä tilassa pyynnöt vain lukevat: mikä tahansa muutos palauttaa 403-vastauksen ja koodin view_as.read_only. OAuth-käyttöoikeustunnus tai avain, jolla ei ole roolia admin, ei voi käyttää X-View-As-otsaketta: tällainen pyyntö palauttaa 403-vastauksen ja koodin view_as.admin_key_required. Otsake, joka ei nimeä mitään olemassa olevaa profiilia, palauttaa 400-vastauksen ja koodin view_as.invalid_header.

Selainsovellukset

API sallii pyynnöt mistä tahansa verkkoalkuperästä (Access-Control-Allow-Origin: *) eikä koskaan käytä evästeitä, joten verkkosivu voi kutsua sitä fetch-funktiolla. Avain on tällöin sivulla ja näkyy jokaiselle, joka sivua käyttää. Kutsu API:a selaimesta vain sellaisella avaimella, jonka voit näyttää näille käyttäjille, kuten julkisiin kokoelmiin rajatulla viewer-avaimella, tai sijoita oma palvelimesi selaimen ja Sursan väliin.

Mitä vain työntekijä voi tehdä

Organisaation API-avain toimii organisaation puolesta, ei henkilön. Kaksi API:n osaa kuuluu ihmisille, joten ne toimivat vain sellaisella tunnistetiedolla, joka toimii työntekijän puolesta: Sursan istunnolla tai OAuth-käyttöoikeustunnuksella, joka on myönnetty työntekijän suostumuksella.

Keskustelut kuuluvat henkilölle. Organisaation API-avain näkee GET /v1/conversations -listassa vain keskustelut, jotka se on itse aloittanut. Julkisessa API:ssa ei ole toimintoa, joka aloittaisi keskustelun, joten avaimelle lista on yleensä tyhjä, eikä työntekijöiden keskusteluja näytetä sille koskaan. Kysymykset ilman keskustelua, POST /v1/ask -pyynnöllä tai POST /v1/chat -pyynnöllä, toimivat millä tahansa avaimella, jolla on käyttöalue ask. Jos haluat listata työntekijän keskustelut ja lukea yhden niistä historian GET /v1/conversations/{conv_id} -pyynnöllä, kutsu API:a OAuth-käyttöoikeustunnuksella kyseisen työntekijän puolesta. Käyttöoikeustunnus näkee vain tämän työntekijän omat keskustelut; mikä tahansa muu keskustelu palauttaa 404-vastauksen ja koodin conversations.not_found.

Vain työntekijä vahvistaa kortin. Vahvistus kertoo, että henkilö on tarkistanut sisällön, joten POST /v1/cards/{card_id}/verification/verify ja POST /v1/cards/{card_id}/verify edellyttävät istuntoa tai OAuth-käyttöoikeustunnusta sellaisen työntekijän puolesta, joka saa vahvistaa kortin. Organisaation API-avaimella tai client_credentials-käyttöoikeustunnuksella ne palauttavat 400-vastauksen ja koodin cards.verify_user_account_required. Tavalliset tarkistukset tehdään ensin: kortti, jota avain ei näe, palauttaa 404-vastauksen, ja avain, joka ei saa vahvistaa korttia, saa 403-vastauksen.