API raktai ir apimtys

Kiekviena užklausa Sursa API siunčiama su jūsų organizacijos API raktu. Raktas priklauso organizacijai, o ne žmogui: jis toliau veikia, kai jį sukūręs darbuotojas išeina, o tai, ką jis gali daryti, nustatoma pačiame rakte.

Ką raktui leidžiama daryti

Trys rakto nustatymai lemia, ką su juo siunčiama užklausa gali matyti ir keisti. Kiekvienas jų tik dar labiau susiaurina kitus.

Nustatymas	Ką jis valdo
Role (vaidmuo)	`admin`, `editor`, `verifier` arba `viewer` – tie patys vaidmenys, kuriuos turi žmonės. Raktas gali daryti tai, ką gali to vaidmens naudotojas.
Scopes (apimtys)	Kurias API dalis raktas gali kviesti, pavyzdžiui, `cards:read` arba `webhooks:manage`. Žr. Raktų apimtys.
Data profile (duomenų profilis)	Nebūtinas. Apriboja raktą žinių kategorijomis, kurias leidžia profilis, kaip ir to profilio naudotoją.

Raktą taip pat galima apriboti keliais rinkiniais ir nustatyti jam galiojimo datą. Užklausa už šių ribų nepavyksta: trūkstant apimties grąžinama 403 su kodu api_keys.scope, o objektui, kurio raktas nemato, grąžinama 404 – lygiai taip, lyg jo nebūtų.

Kiekvienai integracijai suteikite atskirą raktą su siauriausiu reikiamu vaidmeniu ir apimtimis. Sinchronizavimo darbui, kuris tik rašo dokumentus, admin nereikia; ataskaitų darbui nereikia rašymo apimčių.

Sukurkite raktą

Organizacijos administratorius kuria raktus Sursoje, skiltyje Administration → API keys (administravimas, API raktai), arba operacija POST /v1/api-keys, naudodamas raktą ar sesiją su vaidmeniu 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"
  }'

Atsake rakto reikšmė pateikiama lauke key. Ji parodoma vieną kartą: Sursa saugo tik jos maišos reikšmę ir parodyti rakto dar kartą negali. Raktas atrodo kaip kb_ ir po jo 43 simboliai; pirmieji simboliai (prefix) rodomi raktų sąraše, kad raktus galėtumėte atskirti.

Be scopes raktas gauna savo vaidmens apimtis. Perduokite scopes, jei norite jį susiaurinti dar labiau. Be expires_at rakto galiojimas nesibaigia.

Saugokite raktus

Raktus laikykite slaptųjų duomenų saugykloje arba savo paslaugos aplinkos kintamuosiuose, niekada ne pradiniame kode.
Raktus naudokite tik savo serveriuose. Sursa priima užklausas iš naršyklių (CORS atviras), bet tinklalapyje įrašytą raktą mato kiekvienas, kas tą puslapį atidaro.
Niekada nesiųskite rakto URL adrese. Siųskite jį tik antraštėje Authorization.
Jei raktas nutekėjo, iškart jį atšaukite ir sukurkite naują.

Patikrinkite raktą

GET /v1/me grąžina raktą, jo vaidmenį, faktines apimtis, duomenų profilį, galiojimo pabaigą ir užklausų dažnio limitą. Ji veikia su bet kuriuo galiojančiu raktu, kad ir kokios būtų jo apimtys, todėl naudokite ją kaip integracijos ryšio patikrą ir kai aiškinatės atsako 403 priežastį.

Pakeiskite raktą (rotacija)

Rotacija pakeičia raktą nesustabdant integracijos. Greičiausia rakto reikšmę pakeisti nauja: POST /v1/api-keys/{key_id}/roll išduoda naują to paties rakto reikšmę su tuo pačiu vaidmeniu, apimtimis, rinkiniais ir galiojimo pabaiga. Ankstesnė reikšmė veikia dar overlap_hours (numatytai 24 valandas, daugiausia 168), todėl per tą laiką galite įdiegti naująją; POST /v1/api-keys/{key_id}/revoke-previous persidengimą užbaigia anksčiau.

Jei raktą norite pakeisti kitu raktu:

Sukurkite naują raktą su tuo pačiu vaidmeniu, apimtimis ir duomenų profiliu.
Įdiekite naują raktą savo integracijoje.
Stebėkite seną raktą skiltyje Administration → API keys (arba last_used operacijos GET /v1/api-keys atsake), kol jis nebebus naudojamas.
Atšaukite seną raktą.

Nustatykite raktams galiojimo datą ir pakeiskite juos iki jos. Sursa iš anksto įspėja organizacijos administratorius, kad rakto galiojimas baigiasi; raktas, kurio galiojimas baigėsi, grąžina 401 su kodu api_keys.expired.

Atšaukite raktą

Raktą atšaukite skiltyje Administration → API keys arba operacija DELETE /v1/api-keys/{key_id}. Atšaukimas per kelias sekundes įsigalioja visuose API serveriuose. Užklausos su atšauktu raktu grąžina 401 su kodu auth.not_authenticated.

Pasirinktinio šaltinio raktai

Pasirinktinis šaltinis turi savo rūšies raktą. Jis prasideda kbsrc_, gali tik rašyti dokumentus į tą vieną šaltinį ir negali nieko skaityti ar ieškoti. Tai saugiausias raktas, kurį galima duoti integracijų platformai, pavyzdžiui, Zapier. Sukurkite jį šaltinio puslapio skiltyje API keys arba operacija POST /v1/sources/{source_id}/push-keys.

Kai raktų nėra

API raktai priklauso nuo organizacijos plano. Jei planas jų neapima, rakto kūrimas ir kiekviena užklausa su raktu grąžina 403 su kodu api_keys.feature_disabled.