Scopes van sleutels
Een scope geeft een deel van de API aan dat een sleutel mag aanroepen. Elk endpoint in de API-referentie
vermeldt de ene scope die het nodig heeft. Een request met een sleutel zonder die scope wordt geweigerd met 403 en
de code api_keys.scope, voordat er iets wordt gelezen of gewijzigd.
Scopes bepalen welke bewerkingen een sleutel mag aanroepen. Welke objecten die bewerkingen zien, hangt nog steeds af
van de rol, het dataprofiel en de collecties van de sleutel: een sleutel met cards:write en de rol viewer kan
geen kaarten wijzigen, en een sleutel die beperkt is tot één collectie, ziet de andere niet.
Scopes
| Scope | Staat toe |
|---|---|
cards:read | Kaarten, collecties en mappen lezen. |
cards:write | Kaarten, collecties en mappen maken, wijzigen en verwijderen. |
search | Zoeken in de kennisbank (POST /v1/search). |
ask | Vragen stellen aan de assistent (POST /v1/ask, POST /v1/chat). |
import:write | Schrijven naar de eigen bronnen van de organisatie: synchronisaties, batches en verwijderingen, en de toestand ervan lezen. Voor het maken van een bron en de sleutels ervan is admin nodig. |
webhooks:manage | Webhooks beheren en de eventfeed lezen (GET /v1/webhook-events). Voor beide is ook de rol admin nodig. |
users:read | Gebruikers en groepen lezen. |
users:write | Gebruikers en groepen wijzigen. |
analytics:read | Analyses lezen. |
audit:read | Het auditlog lezen. |
finance:read | Financiële rapporten, facturen en betalingen lezen. |
catalog:read | De servicecatalogus lezen. |
files:read | Gegenereerde bestanden lezen, zoals geëxporteerde antwoorden. |
files:write | Gegenereerde bestanden wijzigen en verwijderen. |
permissions:manage | Rechten op objecten toekennen en intrekken. |
admin | De instellingen van de organisatie en haar API-sleutels. Een sleutel met admin heeft ook alle andere scopes. |
Zoeken en vragen stellen gelden als lezen: een sleutel die alleen mag lezen, kan ook zoeken en vragen stellen.
Scopes kiezen
Ken de scopes toe die een integratie gebruikt, en verder niets:
| Integratie | Scopes |
|---|---|
| Vraag-en-antwoordbot in een chattool | search, ask |
| Import uit je documentsysteem | cards:write (API voor kaarten) of import:write (eigen bron) |
| Export naar een datawarehouse | cards:read, users:read en webhooks:manage voor de eventfeed |
| Gebruikers aanmaken vanuit je hr-systeem | users:write |
Geef de lijst mee wanneer je de sleutel maakt:
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"]}'Eerdere scopes
Sleutels die zijn gemaakt voordat de scopes werden opgesplitst, blijven werken. Hun scopes read, write en admin
staan voor deze sets:
| Eerdere scope | Betekent |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | alles uit read, plus cards:write, files:write, users:write, permissions:manage |
admin | alle scopes |
Een sleutel die zonder expliciete scopes is gemaakt, krijgt ze van zijn rol: admin krijgt admin; editor en
verifier krijgen write; viewer krijgt read.
De scopes van een sleutel bekijken
GET /v1/me geeft de scopes terug van de sleutel die het request doet, welke scopes die ook
heeft. Voor een sleutel die zonder expliciete scopes is gemaakt, zijn dat de eerdere scopes van zijn rol, zoals read
en write; de tabel hierboven laat zien waar ze voor staan. Mislukt een bewerking met api_keys.scope, dan noemt
error.message de scope die ontbrak.