API-avaimet ja käyttöalueet

Jokainen Sursa API:n pyyntö tehdään organisaatiosi API-avaimella. Avain kuuluu organisaatiolle eikä henkilölle: se toimii edelleen, kun sen luonut työntekijä lähtee, ja se, mitä avaimella voi tehdä, asetetaan itse avaimeen.

Mitä avain saa tehdä

Avaimen kolme asetusta ratkaisevat, mitä sillä tehty pyyntö voi nähdä ja muuttaa. Kukin niistä vain kaventaa muita.

Asetus	Mitä se ohjaa
Role (rooli)	`admin`, `editor`, `verifier` tai `viewer`, samat roolit kuin ihmisillä. Avain voi tehdä sen, minkä tämän roolin käyttäjäkin.
Scopes (käyttöalueet)	Mitä API:n osia avain saa kutsua, esimerkiksi `cards:read` tai `webhooks:manage`. Ks. Avainten käyttöalueet.
Data profile (dataprofiili)	Valinnainen. Rajaa avaimen niihin tietoluokkiin, jotka profiili sallii, samoin kuin käyttäjän, jolla on tämä profiili.

Avaimen voi myös rajata tiettyihin kokoelmiin, ja sille voi antaa vanhenemispäivän. Näiden rajojen ulkopuolinen pyyntö epäonnistuu: puuttuva käyttöalue palauttaa 403-vastauksen ja koodin api_keys.scope, ja objekti, jota avain ei näe, palauttaa 404, aivan kuin sitä ei olisi olemassa.

Anna jokaiselle integraatiolle oma avain, jolla on suppein tarvittava rooli ja käyttöalueet. Synkronointityö, joka vain kirjoittaa asiakirjoja, ei tarvitse admin-roolia; raportointityö ei tarvitse kirjoituskäyttöalueita.

Avaimen luominen

Organisaation ylläpitäjä luo avaimia Sursassa kohdassa Administration → API keys (ylläpito → API-avaimet) tai POST /v1/api-keys -pyynnöllä käyttäen avainta tai istuntoa, jolla on rooli admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Vastauksen key-kentässä on avaimen arvo. Se näytetään kerran: Sursa säilyttää siitä vain tiivisteen eikä voi näyttää sitä uudelleen. Avain on muotoa kb_ ja sen perässä 43 merkkiä; ensimmäiset merkit (prefix) näkyvät avainluettelossa, jotta voit erottaa avaimet toisistaan.

Ilman scopes-kenttää avain saa roolinsa käyttöalueet. Anna scopes, jos haluat rajata sitä lisää. Ilman expires_at-kenttää avain ei vanhene.

Avainten pitäminen salassa

Säilytä avaimet salaisuuksien hallintapalvelussa tai palvelusi ympäristömuuttujissa, ei koskaan lähdekoodissa.
Käytä avaimia vain palvelimiltasi. Sursa hyväksyy pyyntöjä selaimista (CORS on avoin), mutta verkkosivulla oleva avain näkyy jokaiselle, joka avaa sivun.
Älä koskaan lähetä avainta URL-osoitteessa. Lähetä se vain Authorization-otsakkeessa.
Jos avain vuotaa, peru se heti ja luo uusi.

Avaimen tarkistaminen

GET /v1/me palauttaa avaimen, sen roolin, todelliset käyttöalueet, dataprofiilin, vanhenemisajan ja nopeusrajoituksen. Se toimii millä tahansa kelvollisella avaimella sen käyttöalueista riippumatta, joten käytä sitä integraatiosi yhteystestinä ja silloin, kun selvität 403-vastauksen syytä.

Avaimen uusiminen

Uusiminen korvaa avaimen pysäyttämättä integraatiota. Nopein tapa on uusia avaimen arvo: POST /v1/api-keys/{key_id}/roll myöntää samalle avaimelle uuden arvon, ja rooli, käyttöalueet, kokoelmat ja vanhenemispäivä pysyvät ennallaan. Edellinen arvo toimii vielä overlap_hours-ajan (oletuksena 24 tuntia, enintään 168), joten voit ottaa uuden arvon käyttöön sillä välin; POST /v1/api-keys/{key_id}/revoke-previous päättää päällekkäisyysjakson ennen aikojaan.

Jos haluat sen sijaan korvata avaimen toisella avaimella:

Luo uusi avain, jolla on sama rooli, käyttöalueet ja dataprofiili.
Ota uusi avain käyttöön integraatiossasi.
Seuraa vanhaa avainta kohdassa Administration → API keys (tai last_used-kenttää GET /v1/api-keys -vastauksessa), kunnes sitä ei enää käytetä.
Peru vanha avain.

Aseta avaimille vanhenemispäivä ja uusi ne ennen sitä. Sursa varoittaa organisaation ylläpitäjiä ennen kuin avain vanhenee; avain, jonka voimassaolo on päättynyt, palauttaa 401-vastauksen ja koodin api_keys.expired.

Avaimen peruminen

Peru avain kohdassa Administration → API keys tai DELETE /v1/api-keys/{key_id} -pyynnöllä. Peruminen tulee voimaan sekunneissa jokaisessa API-instanssissa. Perutulla avaimella tehdyt pyynnöt palauttavat 401-vastauksen ja koodin auth.not_authenticated.

Mukautetun lähteen avaimet

Mukautetulla lähteellä on oma avainlajinsa. Sen alussa on kbsrc_, sillä voi vain kirjoittaa asiakirjoja tähän yhteen lähteeseen, eikä sillä voi lukea tai hakea mitään. Se on turvallisin avain annettavaksi integraatioalustalle, kuten Zapierille. Luo se lähteen sivun API keys -osiossa tai POST /v1/sources/{source_id}/push-keys -pyynnöllä.

Kun avaimet eivät ole käytettävissä

API-avaimet kuuluvat organisaation pakettiin. Jos paketti ei sisällä niitä, avaimen luominen ja jokainen avaimella tehty pyyntö palauttavat 403-vastauksen ja koodin api_keys.feature_disabled.