Scopes for nøgler

Et scope angiver en del af API’et, som en nøgle må kalde. Hver operation i API-referencen angiver det ene scope, den kræver. En anmodning med en nøgle, der mangler det, afvises med 403 og koden api_keys.scope, før noget læses eller ændres.

Scopes bestemmer, hvilke operationer en nøgle må kalde. Nøglens rolle, dataprofil og samlinger bestemmer stadig, hvilke objekter disse operationer ser: En nøgle med cards:write og rollen viewer kan ikke ændre kort, og en nøgle, der er begrænset til én samling, ser ikke de andre.

Alle scopes

Scope	Tillader
`cards:read`	Læse kort, samlinger og mapper.
`cards:write`	Oprette, ændre og slette kort, samlinger og mapper.
`search`	Søge i vidensbasen (`POST /v1/search`).
`ask`	Stille spørgsmål til assistenten (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	Skrive i organisationens brugerdefinerede kilder: synkroniseringer, batches og sletninger, og læse deres tilstand. Oprettelse af en kilde og dens nøgler kræver `admin`.
`webhooks:manage`	Administrere webhook-slutpunkter og læse hændelsesfeedet (`GET /v1/webhook-events`). Begge kræver også rollen `admin`.
`users:read`	Læse brugere og grupper.
`users:write`	Ændre brugere og grupper.
`analytics:read`	Læse produktanalyse.
`audit:read`	Læse revisionsloggen.
`finance:read`	Læse økonomiske rapporter, fakturaer og betalinger.
`catalog:read`	Læse tjenestekataloget.
`files:read`	Læse genererede filer, fx eksporterede svar.
`files:write`	Ændre og slette genererede filer.
`permissions:manage`	Tildele og tilbagekalde tilladelser på objekter.
`admin`	Organisationens indstillinger og dens API-nøgler. En nøgle med `admin` har også alle andre scopes.

Søgning og spørgsmål regnes som læsning: En nøgle, der kun må læse, kan stadig søge og stille spørgsmål.

Valg af scopes

Tildel de scopes, som en integration bruger, og intet andet:

Integration	Scopes
Q&A-bot i et chatværktøj	`search`, `ask`
Import fra dit dokumentsystem	`cards:write` (kort-API’et) eller `import:write` (brugerdefineret kilde)
Eksport til et datavarehus	`cards:read`, `users:read` og `webhooks:manage` til hændelsesfeedet
Oprettelse af brugere fra dit HR-system	`users:write`

Angiv listen, når du opretter nøglen:

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øgler, der blev oprettet, før scopes blev opdelt, virker fortsat. Deres scopes read, write og admin står for disse sæt:

Tidligere scope	Betyder
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	alt i `read` plus `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	alle scopes

En nøgle, der er oprettet uden udtrykkelige scopes, får dem fra sin rolle: admin får admin; editor og verifier får write; viewer får read.

Sådan ser du en nøgles scopes

GET /v1/me returnerer scopes for den nøgle, der sender anmodningen, uanset hvilke scopes den har. For en nøgle, der er oprettet uden eksplicitte scopes, er det rollens tidligere scopes, fx read og write; tabellen ovenfor viser, hvad de står for. Når en operation mislykkes med api_keys.scope, angiver error.message det scope, der manglede.