API ključevi i opsezi

Svaki zahtjev prema Sursa API-ju šalje se s API ključem vaše organizacije. Ključ pripada organizaciji, a ne osobi: nastavlja raditi kad zaposlenik koji ga je stvorio ode, a ono što može činiti postavlja se na samom ključu.

Što ključ smije činiti

Tri postavke ključa određuju što zahtjev s njim može vidjeti i promijeniti. Svaka od njih samo sužava ostale.

Postavka	Što određuje
Uloga	`admin`, `editor`, `verifier` ili `viewer`, iste uloge koje imaju ljudi. Ključ može činiti ono što može korisnik s tom ulogom.
Opsezi	Koje dijelove API-ja ključ smije pozivati, na primjer `cards:read` ili `webhooks:manage`. V. Opsezi ključeva.
Podatkovni profil	Neobavezno. Ograničava ključ na kategorije znanja koje profil dopušta, kao korisnika s tim profilom.

Ključ se može ograničiti i na neke zbirke te mu se može postaviti rok valjanosti. Zahtjev izvan tih ograničenja ne uspijeva: nedostajući opseg vraća 403 s kodom api_keys.scope, a objekt koji ključ ne smije vidjeti vraća 404, točno kao da ne postoji.

Svakoj integraciji dodijelite vlastiti ključ s najužom ulogom i opsezima koji su joj potrebni. Poslu sinkronizacije koji samo zapisuje dokumente ne treba admin; poslu izvješćivanja ne trebaju opsezi za pisanje.

Stvaranje ključa

Administrator organizacije stvara ključeve u Sursi u Administration → API keys (administracija, API ključevi) ili pomoću POST /v1/api-keys s ključem ili sesijom koja ima ulogu 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"
  }'

Odgovor sadrži vrijednost ključa u key. Prikazuje se jednom: Sursa čuva samo njezin sažetak (hash) i ne može je ponovno prikazati. Ključ izgleda kao kb_ iza kojeg slijede 43 znaka; prvi znakovi (prefix) prikazuju se u popisu ključeva kako biste ključeve mogli razlikovati.

Bez scopes ključ dobiva opsege svoje uloge. Proslijedite scopes da biste ga dodatno suzili. Bez expires_at ključ ne istječe.

Čuvanje ključeva u tajnosti

Ključeve pohranjujte u spremištu tajni ili u varijablama okruženja svoje usluge, nikada u izvornom kodu.
Ključeve koristite samo sa svojih poslužitelja. Sursa prihvaća zahtjeve iz preglednika (CORS je otvoren), ali ključ na web-stranici vidljiv je svakome tko je otvori.
Nikada ne šaljite ključ u URL-u. Šaljite ga samo u zaglavlju Authorization.
Ako ključ procuri, odmah ga opozovite i stvorite novi.

Provjera ključa

GET /v1/me vraća ključ, njegovu ulogu, stvarne opsege, podatkovni profil, rok valjanosti i ograničenje učestalosti. Radi s bilo kojim valjanim ključem, bez obzira na njegove opsege, pa ga koristite kao test veze svoje integracije i kad istražujete 403.

Rotacija ključa

Rotacija zamjenjuje ključ bez zaustavljanja integracije. Najbrži je način ponovno izdavanje ključa: POST /v1/api-keys/{key_id}/roll izdaje novu vrijednost za isti ključ, s istom ulogom, opsezima, zbirkama i rokom valjanosti. Prethodna vrijednost radi još overlap_hours (zadano 24 sata, najviše 168), pa u međuvremenu možete uvesti novu vrijednost; POST /v1/api-keys/{key_id}/revoke-previous prijevremeno završava preklapanje.

Da biste ključ umjesto toga zamijenili drugim ključem:

Stvorite novi ključ s istom ulogom, opsezima i podatkovnim profilom.
Uvedite novi ključ u svoju integraciju.
Pratite stari ključ u Administration → API keys (ili last_used u GET /v1/api-keys) dok se više ne bude koristio.
Opozovite stari ključ.

Ključevima postavite rok valjanosti i rotirajte ih prije njegova isteka. Sursa upozorava administratore organizacije prije nego što ključ istekne; istekli ključ vraća 401 s kodom api_keys.expired.

Opoziv ključa

Ključ opozovite u Administration → API keys ili pomoću DELETE /v1/api-keys/{key_id}. Opoziv stupa na snagu u roku od nekoliko sekundi na svakom poslužitelju API-ja. Zahtjevi s opozvanim ključem vraćaju 401 s kodom auth.not_authenticated.

Ključevi vlastitog izvora

Vlastiti izvor ima vlastitu vrstu ključa. Počinje s kbsrc_, može samo zapisivati dokumente u taj jedan izvor i ne može ništa čitati ni pretraživati. To je najsigurniji ključ koji možete dati platformi za integracije kao što je Zapier. Stvorite ga na stranici izvora u odjeljku API keys ili pomoću POST /v1/sources/{source_id}/push-keys.

Kad ključevi nisu dostupni

API ključevi dio su plana organizacije. Ako ih plan ne uključuje, stvaranje ključa i svaki zahtjev s ključem vraćaju 403 s kodom api_keys.feature_disabled.