Domeniile de acces ale cheilor
Un domeniu de acces numește o parte a API-ului pe care o cheie o poate apela. Fiecare endpoint din referința API
declară domeniul de care are nevoie. O cerere cu o cheie care nu îl are este refuzată cu 403 și codul
api_keys.scope, înainte să fie citit sau modificat ceva.
Domeniile spun ce operații poate apela o cheie. Rolul cheii, profilul de date și colecțiile decid în continuare ce
obiecte văd acele operații: o cheie cu cards:write și rolul viewer nu poate modifica fișe, iar o cheie limitată la
o colecție nu le vede pe celelalte.
Domenii
| Domeniu | Permite |
|---|---|
cards:read | Citirea fișelor, colecțiilor și dosarelor. |
cards:write | Crearea, modificarea și ștergerea fișelor, colecțiilor și dosarelor. |
search | Căutarea în baza de cunoștințe (POST /v1/search). |
ask | Întrebările adresate asistentului (POST /v1/ask, POST /v1/chat). |
import:write | Scrierea în sursele personalizate ale organizației: sincronizări, loturi și ștergeri, precum și citirea stării lor. Crearea unei surse și a cheilor ei necesită admin. |
webhooks:manage | Gestionarea webhookurilor și citirea fluxului de evenimente (GET /v1/webhook-events). Ambele necesită și rolul admin. |
users:read | Citirea utilizatorilor și a grupurilor. |
users:write | Modificarea utilizatorilor și a grupurilor. |
analytics:read | Citirea analizelor. |
audit:read | Citirea jurnalului de audit. |
finance:read | Citirea rapoartelor financiare, a facturilor și a plăților. |
catalog:read | Citirea catalogului de servicii. |
files:read | Citirea fișierelor generate, cum ar fi răspunsurile exportate. |
files:write | Modificarea și ștergerea fișierelor generate. |
permissions:manage | Acordarea și revocarea permisiunilor pe obiecte. |
admin | Setările organizației și cheile ei API. O cheie cu admin are și toate celelalte domenii. |
Căutarea și întrebările sunt, ca sens, operații de citire: o cheie care poate doar să citească poate totuși să caute și să pună întrebări.
Alegerea domeniilor
Acordați domeniile pe care o integrare le folosește și nimic în plus:
| Integrare | Domenii |
|---|---|
| Bot de întrebări și răspunsuri într-o aplicație de chat | search, ask |
| Import din sistemul propriu de documente | cards:write (API-ul fișelor) sau import:write (sursă personalizată) |
| Export într-un depozit de date | cards:read, users:read și webhooks:manage pentru fluxul de evenimente |
| Crearea utilizatorilor din sistemul de resurse umane | users:write |
Transmiteți lista când creați cheia:
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"]}'Domenii anterioare
Cheile create înainte de împărțirea domeniilor funcționează în continuare. Domeniile lor read, write și admin
înseamnă următoarele seturi:
| Domeniu anterior | Înseamnă |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | tot ce include read, plus cards:write, files:write, users:write, permissions:manage |
admin | toate domeniile |
O cheie creată fără domenii explicite le primește de la rolul ei: admin primește admin; editor și verifier
primesc write; viewer primește read.
Domeniile unei chei
GET /v1/me returnează domeniile cheii care face cererea, oricare ar fi domeniile ei.
Pentru o cheie creată fără domenii explicite, acestea sunt domeniile anterioare ale rolului ei, cum ar fi read și
write; tabelul de mai sus arată ce înseamnă ele. Când o operație eșuează cu api_keys.scope, error.message
numește domeniul care lipsea.