Avainten käyttöalueet
Käyttöalue nimeää sen osan API:sta, jota avain saa kutsua. API-viitteen jokainen päätepiste ilmoittaa
yhden käyttöalueen, jonka se tarvitsee. Jos avaimelta puuttuu tämä käyttöalue, pyyntö hylätään 403-vastauksella ja
koodilla api_keys.scope ennen kuin mitään luetaan tai muutetaan.
Käyttöalueet kertovat, mitä toimintoja avain saa kutsua. Avaimen rooli, dataprofiili ja kokoelmat ratkaisevat
edelleen, mitkä objektit nämä toiminnot näkevät: avain, jolla on cards:write ja rooli viewer, ei voi muuttaa
kortteja, eikä yhteen kokoelmaan rajattu avain näe muita kokoelmia.
Käyttöalueet
| Käyttöalue | Sallii |
|---|---|
cards:read | Korttien, kokoelmien ja kansioiden lukemisen. |
cards:write | Korttien, kokoelmien ja kansioiden luomisen, muuttamisen ja poistamisen. |
search | Haun tietopankista (POST /v1/search). |
ask | Kysymysten esittämisen avustajalle (POST /v1/ask, POST /v1/chat). |
import:write | Kirjoittamisen organisaation mukautettuihin lähteisiin (synkronoinnit, erät ja poistot) sekä niiden tilan lukemisen. Lähteen ja sen avainten luomiseen tarvitaan admin. |
webhooks:manage | Webhookien hallinnan ja tapahtumasyötteen lukemisen (GET /v1/webhook-events). Molemmat edellyttävät myös roolia admin. |
users:read | Käyttäjien ja ryhmien lukemisen. |
users:write | Käyttäjien ja ryhmien muuttamisen. |
analytics:read | Analytiikan lukemisen. |
audit:read | Tarkastuslokin lukemisen. |
finance:read | Talousraporttien, laskujen ja maksujen lukemisen. |
catalog:read | Palveluluettelon lukemisen. |
files:read | Luotujen tiedostojen, kuten vietyjen vastausten, lukemisen. |
files:write | Luotujen tiedostojen muuttamisen ja poistamisen. |
permissions:manage | Objektien käyttöoikeuksien määrittämisen ja poistamisen. |
admin | Organisaation asetusten ja sen API-avainten hallinnan. Avaimella, jolla on admin, on myös kaikki muut käyttöalueet. |
Haku ja kysymykset ovat luonteeltaan lukemista: avain, joka saa vain lukea, voi silti hakea ja kysyä.
Käyttöalueiden valinta
Anna integraatiolle ne käyttöalueet, joita se käyttää, eikä mitään muuta:
| Integraatio | Käyttöalueet |
|---|---|
| Kysymys–vastaus-botti chat-työkalussa | search, ask |
| Tuonti asiakirjajärjestelmästäsi | cards:write (korttien API) tai import:write (mukautettu lähde) |
| Vienti tietovarastoon | cards:read, users:read ja tapahtumasyötettä varten webhooks:manage |
| Käyttäjien hallinta HR-järjestelmästäsi | users:write |
Anna luettelo, kun luot avaimen:
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"]}'Aiemmat käyttöalueet
Avaimet, jotka on luotu ennen käyttöalueiden jakamista pienempiin osiin, toimivat edelleen. Niiden käyttöalueet read,
write ja admin tarkoittavat seuraavia joukkoja:
| Aiempi käyttöalue | Tarkoittaa |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | kaikki read-käyttöalueen sisältö sekä cards:write, files:write, users:write, permissions:manage |
admin | kaikki käyttöalueet |
Avain, joka on luotu ilman nimenomaisia käyttöalueita, saa ne roolistaan: admin saa käyttöalueen admin; editor
ja verifier saavat käyttöalueen write; viewer saa käyttöalueen read.
Avaimen käyttöalueiden tarkistaminen
GET /v1/me palauttaa pyynnön tekevän avaimen käyttöalueet, olivatpa ne mitkä tahansa.
Ilman nimenomaisia käyttöalueita luodulla avaimella nämä ovat sen roolin aiemmat käyttöalueet, kuten read ja
write; yllä oleva taulukko näyttää, mitä ne tarkoittavat. Kun toiminto epäonnistuu koodilla api_keys.scope,
error.message kertoo, mikä käyttöalue puuttui.