Nycklarnas omfång
Ett omfång anger en del av API:et som en nyckel får anropa. Varje slutpunkt i API-referensen anger det
enda omfång som den kräver. Ett anrop med en nyckel som saknar det avvisas med 403 och koden
api_keys.scope, innan något läses eller ändras.
Omfången säger vilka åtgärder en nyckel får anropa. Nyckelns roll, dataprofil och samlingar avgör fortfarande vilka
objekt som åtgärderna ser: en nyckel med cards:write och rollen viewer kan inte ändra kort, och en nyckel som är
begränsad till en samling ser inte de andra.
Omfång
| Omfång | Tillåter |
|---|---|
cards:read | Läsa kort, samlingar och mappar. |
cards:write | Skapa, ändra och ta bort kort, samlingar och mappar. |
search | Söka i kunskapsbasen (POST /v1/search). |
ask | Ställa frågor till assistenten (POST /v1/ask, POST /v1/chat). |
import:write | Skriva till organisationens egna källor: synkningar, batchar och borttagningar, och läsa deras tillstånd. För att skapa en källa och dess nycklar krävs admin. |
webhooks:manage | Hantera webhookar och läsa händelseflödet (GET /v1/webhook-events). Båda kräver också rollen admin. |
users:read | Läsa användare och grupper. |
users:write | Ändra användare och grupper. |
analytics:read | Läsa analysdata. |
audit:read | Läsa granskningsloggen. |
finance:read | Läsa finansiella rapporter, fakturor och betalningar. |
catalog:read | Läsa tjänstekatalogen. |
files:read | Läsa genererade filer, till exempel exporterade svar. |
files:write | Ändra och ta bort genererade filer. |
permissions:manage | Tilldela och återkalla behörigheter för objekt. |
admin | Organisationens inställningar och dess API-nycklar. En nyckel med admin har även alla andra omfång. |
Sökningar och frågor räknas som läsning: en nyckel som bara får läsa kan ändå söka och ställa frågor.
Välja omfång
Ge de omfång som en integration använder och inget annat:
| Integration | Omfång |
|---|---|
| Fråga-svar-bot i ett chattverktyg | search, ask |
| Import från ditt dokumentsystem | cards:write (API:et för kort) eller import:write (egen källa) |
| Export till ett datalager | cards:read, users:read och webhooks:manage för händelseflödet |
| Etablering av användare från ditt HR-system | users:write |
Skicka listan när du skapar nyckeln:
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"]}'Tidigare omfång
Nycklar som skapades innan omfången delades upp fungerar fortfarande. Deras omfång read, write och admin står för
följande uppsättningar:
| Tidigare omfång | Betyder |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | allt i read samt cards:write, files:write, users:write, permissions:manage |
admin | alla omfång |
En nyckel som skapas utan uttryckliga omfång får dem från sin roll: admin får admin; editor och verifier får
write; viewer får read.
Se en nyckels omfång
GET /v1/me returnerar omfången för nyckeln som gör anropet, oavsett vilka omfång den har.
För en nyckel som skapades utan uttryckliga omfång är det rollens tidigare omfång, till exempel read och write;
tabellen ovan visar vad de står för. När en åtgärd misslyckas med api_keys.scope anger error.message vilket
omfång som saknades.