A kulcsok hatókörei

A hatókör az API-nak azt a részét nevezi meg, amelyet egy kulcs hívhat. Az API-referencia minden végpontja megadja azt az egy hatókört, amelyre szüksége van. Ha a kérés kulcsából ez hiányzik, a Sursa 403 válasszal és az api_keys.scope kóddal elutasítja, még mielőtt bármit beolvasna vagy módosítana.

A hatókörök azt mondják meg, mely műveleteket hívhat a kulcs. Azt viszont, hogy ezek a műveletek mely objektumokat látják, továbbra is a kulcs szerepköre, adatprofilja és gyűjteményei döntik el: a cards:write hatókörű, viewer szerepkörű kulcs nem módosíthat kártyákat, az egy gyűjteményre korlátozott kulcs pedig nem látja a többit.

Hatókörök

Hatókör	Mit enged
`cards:read`	Kártyák, gyűjtemények és mappák olvasása.
`cards:write`	Kártyák, gyűjtemények és mappák létrehozása, módosítása és törlése.
`search`	Keresés a tudásbázisban (`POST /v1/search`).
`ask`	Kérdések az asszisztensnek (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Írás a szervezet egyéni forrásaiba: szinkronizálások, kötegek és törlések, valamint ezek állapotának olvasása. Egy forrás és a kulcsai létrehozásához `admin` szükséges.
`webhooks:manage`	Webhookok kezelése és az eseménycsatorna olvasása (`GET /v1/webhook-events`). Mindkettőhöz az `admin` szerepkör is kell.
`users:read`	Felhasználók és csoportok olvasása.
`users:write`	Felhasználók és csoportok módosítása.
`analytics:read`	Analitika olvasása.
`audit:read`	Az auditnapló olvasása.
`finance:read`	Pénzügyi jelentések, számlák és kifizetések olvasása.
`catalog:read`	A szolgáltatáskatalógus olvasása.
`files:read`	Generált fájlok, például exportált válaszok olvasása.
`files:write`	Generált fájlok módosítása és törlése.
`permissions:manage`	Jogosultságok kiosztása és visszavonása objektumokon.
`admin`	A szervezet beállításai és API-kulcsai. Az `admin` hatókörű kulcs minden más hatókörrel is rendelkezik.

A keresés és a kérdezés jellegét tekintve olvasás: a csak olvasásra jogosult kulcs is kereshet és kérdezhet.

Hatókörök kiválasztása

Csak azokat a hatóköröket add meg, amelyeket az integráció használ, semmi mást:

Integráció	Hatókörök
Kérdés-válasz bot egy csevegőeszközben	`search`, `ask`
Importálás a dokumentumkezelő rendszeredből	`cards:write` (kártya-API) vagy `import:write` (egyéni forrás)
Exportálás adattárházba	`cards:read`, `users:read`, valamint `webhooks:manage` az eseménycsatornához
Felhasználók létrehozása a HR-rendszeredből	`users:write`

A listát a kulcs létrehozásakor add meg:

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"]}'

Korábbi hatókörök

A hatókörök szétválasztása előtt létrehozott kulcsok továbbra is működnek. A read, a write és az admin hatókörük a következő készleteket jelenti:

Korábbi hatókör	Jelentése
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	minden, ami a `read` hatókörben, továbbá `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	minden hatókör

A kifejezett hatókörök nélkül létrehozott kulcs a szerepköréből kapja meg őket: az admin az admin hatókört; az editor és a verifier a write hatókört; a viewer a read hatókört.

Egy kulcs hatóköreinek megtekintése

A GET /v1/me a kérést küldő kulcs hatóköreit adja vissza, bármilyen hatókörei is vannak. A kifejezett hatókörök nélkül létrehozott kulcsnál ezek a szerepköre korábbi hatókörei, például read és write; a fenti táblázat mutatja, mit jelentenek. Ha egy művelet az api_keys.scope kóddal hiúsul meg, az error.message megnevezi a hiányzó hatókört.