Võtmete ulatused

Ulatus nimetab API osa, mida võti võib kutsuda. API teatmikus deklareerib iga lõpp-punkt ühe ulatuse, mida see vajab. Päring võtmega, millel see ulatus puudub, lükatakse tagasi vastusega 403 ja koodiga api_keys.scope enne, kui midagi loetakse või muudetakse.

Ulatused määravad, milliseid toiminguid võti võib kutsuda. Seda, milliseid objekte need toimingud näevad, määravad endiselt võtme roll, andmeprofiil ja kogud: võti, millel on ulatus cards:write ja roll viewer, ei saa kaarte muuta, ja ühe koguga piiratud võti teisi kogusid ei näe.

Ulatused

Ulatus	Lubab
`cards:read`	Kaartide, kogude ja kaustade lugemine.
`cards:write`	Kaartide, kogude ja kaustade loomine, muutmine ja kustutamine.
`search`	Otsing teadmusbaasist (`POST /v1/search`).
`ask`	Küsimused assistendile (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Kirjutamine organisatsiooni kohandatud allikatesse: sünkroonimised, partiid ja kustutamised, ning nende oleku lugemine. Allika ja selle võtmete loomiseks on vaja ulatust `admin`.
`webhooks:manage`	Veebihaagide haldamine ja sündmuste lindi lugemine (`GET /v1/webhook-events`). Mõlemaks on vaja ka rolli `admin`.
`users:read`	Kasutajate ja rühmade lugemine.
`users:write`	Kasutajate ja rühmade muutmine.
`analytics:read`	Analüütika lugemine.
`audit:read`	Auditilogi lugemine.
`finance:read`	Finantsaruannete, arvete ja maksete lugemine.
`catalog:read`	Teenuste kataloogi lugemine.
`files:read`	Genereeritud failide, näiteks eksporditud vastuste lugemine.
`files:write`	Genereeritud failide muutmine ja kustutamine.
`permissions:manage`	Objektide õiguste andmine ja tühistamine.
`admin`	Organisatsiooni ja selle API-võtmete seaded. Ulatusega `admin` võtmel on ka kõik muud ulatused.

Otsing ja küsimused on oma olemuselt lugemine: võti, mis tohib ainult lugeda, saab siiski otsida ja küsida.

Ulatuste valimine

Andke integratsioonile need ulatused, mida see kasutab, ja mitte midagi muud:

Integratsioon	Ulatused
Küsimuste ja vastuste bot vestlusrakenduses	`search`, `ask`
Import teie dokumendisüsteemist	`cards:write` (kaartide API) või `import:write` (kohandatud allikas)
Eksport andmelattu	`cards:read`, `users:read` ja sündmuste lindi jaoks `webhooks:manage`
Kasutajate loomine ja muutmine teie personalisüsteemi põhjal	`users:write`

Edastage loend võtme loomisel:

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

Varasemad ulatused

Võtmed, mis loodi enne ulatuste jagamist, töötavad edasi. Nende ulatused read, write ja admin tähistavad järgmisi komplekte:

Varasem ulatus	Tähendab
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	kõik, mis on ulatuses `read`, ning lisaks `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	kõik ulatused

Ilma selgesõnaliste ulatusteta loodud võti saab need oma rollist: roll admin saab ulatuse admin; rollid editor ja verifier saavad ulatuse write; roll viewer saab ulatuse read.

Võtme ulatuste vaatamine

GET /v1/me tagastab päringu teinud võtme ulatused, olenemata sellest, millised ulatused sellel on. Ilma selgesõnaliste ulatusteta loodud võtme puhul on need tema rolli varasemad ulatused, näiteks read ja write; ülaltoodud tabel näitab, mida need tähendavad. Kui toiming ebaõnnestub koodiga api_keys.scope, nimetab error.message puuduva ulatuse.