Opsezi ključeva

Opseg imenuje dio API-ja koji ključ smije pozivati. Svaka operacija u referenci API-ja navodi jedan opseg koji joj je potreban. Zahtjev s ključem koji ga nema odbija se s 403 i kodom api_keys.scope, prije nego što se išta pročita ili promijeni.

Opsezi određuju koje operacije ključ smije pozivati. Uloga ključa, njegov podatkovni profil i zbirke i dalje određuju koje objekte te operacije vide: ključ s opsegom cards:write i ulogom viewer ne može mijenjati kartice, a ključ ograničen na jednu zbirku ne vidi ostale.

Opsezi

Opseg	Dopušta
`cards:read`	Čitanje kartica, zbirki i mapa.
`cards:write`	Stvaranje, mijenjanje i brisanje kartica, zbirki i mapa.
`search`	Pretraživanje baze znanja (`POST /v1/search`).
`ask`	Pitanja asistentu (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Pisanje u vlastite izvore organizacije: sinkronizacije, paketi i brisanja te čitanje njihova stanja. Za stvaranje izvora i njegovih ključeva potreban je `admin`.
`webhooks:manage`	Upravljanje webhookovima i čitanje feeda događaja (`GET /v1/webhook-events`). Za oboje je potrebna i uloga `admin`.
`users:read`	Čitanje korisnika i grupa.
`users:write`	Mijenjanje korisnika i grupa.
`analytics:read`	Čitanje analitike.
`audit:read`	Čitanje revizijskog zapisnika.
`finance:read`	Čitanje financijskih izvješća, računa i plaćanja.
`catalog:read`	Čitanje kataloga usluga.
`files:read`	Čitanje generiranih datoteka, kao što su izvezeni odgovori.
`files:write`	Mijenjanje i brisanje generiranih datoteka.
`permissions:manage`	Dodjela i opoziv dopuštenja na objektima.
`admin`	Postavke organizacije i njezini API ključevi. Ključ s opsegom `admin` ima i sve ostale opsege.

Pretraživanje i pitanja po svojoj su naravi čitanje: ključ koji smije samo čitati i dalje može pretraživati i postavljati pitanja.

Odabir opsega

Dodijelite opsege koje integracija koristi i ništa više:

Integracija	Opsezi
Bot za pitanja i odgovore u alatu za chat	`search`, `ask`
Uvoz iz vašeg sustava za dokumente	`cards:write` (API kartica) ili `import:write` (vlastiti izvor)
Izvoz u skladište podataka	`cards:read`, `users:read` i `webhooks:manage` za feed događaja
Dodavanje korisnika iz vašeg kadrovskog sustava	`users:write`

Popis proslijedite pri stvaranju ključa:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'

Raniji opsezi

Ključevi stvoreni prije podjele opsega i dalje rade. Njihovi opsezi read, write i admin označavaju ove skupove:

Raniji opseg	Znači
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	sve iz `read`, uz `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	svi opsezi

Ključ stvoren bez izričito navedenih opsega dobiva ih prema svojoj ulozi: admin dobiva admin; editor i verifier dobivaju write; viewer dobiva read.

Pregled opsega ključa

GET /v1/me vraća opsege ključa koji šalje zahtjev, bez obzira na to koje opsege ima. Za ključ stvoren bez izričito navedenih opsega to su raniji opsezi njegove uloge, kao što su read i write; tablica iznad pokazuje što oni znače. Kad operacija ne uspije s api_keys.scope, error.message navodi opseg koji je nedostajao.