Nøklenes scopes
Et scope angir en del av API-et som en nøkkel kan kalle. Hver operasjon i API-referansen oppgir det ene
scopet den trenger. En forespørsel med en nøkkel som mangler det, avvises med 403 og koden
api_keys.scope før noe leses eller endres.
Scopes sier hvilke operasjoner en nøkkel kan kalle. Nøkkelens rolle, dataprofil og samlinger avgjør likevel hvilke
objekter disse operasjonene ser: En nøkkel med cards:write og rollen viewer kan ikke endre kort, og en nøkkel som
er begrenset til én samling, ser ikke de andre.
Oversikt over scopes
| Scope | Tillater |
|---|---|
cards:read | Lese kort, samlinger og mapper. |
cards:write | Opprette, endre og slette kort, samlinger og mapper. |
search | Søke i kunnskapsbasen (POST /v1/search). |
ask | Spørre assistenten (POST /v1/ask, POST /v1/chat). |
import:write | Skrive til organisasjonens egendefinerte kilder: synkroniseringer, batcher og slettinger, og lese tilstanden deres. Å opprette en kilde og nøklene til den krever admin. |
webhooks:manage | Administrere webhook-endepunkter og lese hendelsesfeeden (GET /v1/webhook-events). Begge deler krever også rollen admin. |
users:read | Lese brukere og grupper. |
users:write | Endre brukere og grupper. |
analytics:read | Lese analyser. |
audit:read | Lese revisjonsloggen. |
finance:read | Lese økonomiske rapporter, fakturaer og betalinger. |
catalog:read | Lese tjenestekatalogen. |
files:read | Lese genererte filer, for eksempel eksporterte svar. |
files:write | Endre og slette genererte filer. |
permissions:manage | Tildele og trekke tilbake tillatelser på objekter. |
admin | Organisasjonens innstillinger og API-nøkler. En nøkkel med admin har også alle de andre scopene. |
Søk og spørsmål er i praksis lesing: En nøkkel som bare har lov til å lese, kan likevel søke og spørre.
Velge scopes
Gi de scopene som en integrasjon bruker, og ingen andre:
| Integrasjon | Scopes |
|---|---|
| Spørsmål-og-svar-bot i et chatteverktøy | search, ask |
| Import fra dokumentsystemet ditt | cards:write (kort-API-et) eller import:write (egendefinert kilde) |
| Eksport til et datavarehus | cards:read, users:read og webhooks:manage for hendelsesfeeden |
| Klargjøring av brukere fra HR-systemet ditt | users:write |
Oppgi listen når du oppretter nøkkelen:
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"]}'Tidligere scopes
Nøkler som ble opprettet før scopene ble delt opp, fungerer fortsatt. Scopene deres read, write og admin står
for disse settene:
| Tidligere scope | Betyr |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | alt i read, pluss cards:write, files:write, users:write, permissions:manage |
admin | alle scopes |
En nøkkel som er opprettet uten eksplisitte scopes, får dem fra rollen sin: admin får admin, editor og
verifier får write, og viewer får read.
Se scopene til en nøkkel
GET /v1/me returnerer scopene til nøkkelen som sender forespørselen, uansett hvilke scopes
den har. For en nøkkel som er opprettet uten eksplisitte scopes, er dette de tidligere scopene til rollen, for
eksempel read og write; tabellen ovenfor viser hva de står for. Når en operasjon mislykkes med api_keys.scope,
oppgir error.message scopet som manglet.