Scopes von Schlüsseln

Ein Scope benennt einen Teil der API, den ein Schlüssel aufrufen darf. Jeder Endpunkt der API-Referenz gibt den einen Scope an, den er benötigt. Eine Anfrage mit einem Schlüssel ohne diesen Scope wird mit 403 und dem Code api_keys.scope abgelehnt, bevor etwas gelesen oder geändert wird.

Scopes legen fest, welche Operationen ein Schlüssel aufrufen darf. Welche Objekte diese Operationen sehen, bestimmen weiterhin Rolle, Datenprofil und Sammlungen des Schlüssels: Ein Schlüssel mit cards:write und der Rolle viewer kann keine Karten ändern, und ein Schlüssel, der auf eine Sammlung beschränkt ist, sieht die anderen nicht.

Scopes

Scope	Erlaubt
`cards:read`	Karten, Sammlungen und Ordner lesen.
`cards:write`	Karten, Sammlungen und Ordner erstellen, ändern und löschen.
`search`	Die Wissensbasis durchsuchen (`POST /v1/search`).
`ask`	Dem Assistenten Fragen stellen (`POST /v1/ask`, `POST /v1/chat`).
`import:write`	In die benutzerdefinierten Quellen der Organisation schreiben: Synchronisierungen, Batches und Löschungen; außerdem deren Zustand lesen. Das Anlegen einer Quelle und ihrer Schlüssel erfordert `admin`.
`webhooks:manage`	Webhook-Endpunkte verwalten und den Ereignis-Feed lesen (`GET /v1/webhook-events`). Für beides ist außerdem die Rolle `admin` nötig.
`users:read`	Benutzer und Gruppen lesen.
`users:write`	Benutzer und Gruppen ändern.
`analytics:read`	Analysen lesen.
`audit:read`	Das Audit-Log lesen.
`finance:read`	Finanzberichte, Rechnungen und Zahlungen lesen.
`catalog:read`	Den Dienstkatalog lesen.
`files:read`	Erzeugte Dateien lesen, etwa exportierte Antworten.
`files:write`	Erzeugte Dateien ändern und löschen.
`permissions:manage`	Berechtigungen für Objekte erteilen und entziehen.
`admin`	Die Einstellungen der Organisation und ihre API-Schlüssel. Ein Schlüssel mit `admin` hat zugleich jeden anderen Scope.

Suche und Fragen sind ihrem Wesen nach Lesezugriffe: Ein Schlüssel, der nur lesen darf, kann trotzdem suchen und fragen.

Scopes auswählen

Erteilen Sie genau die Scopes, die eine Integration verwendet, und keine weiteren:

Integration	Scopes
Q&A-Bot in einem Chat-Tool	`search`, `ask`
Import aus Ihrem Dokumentensystem	`cards:write` (Karten-API) oder `import:write` (benutzerdefinierte Quelle)
Export in ein Data Warehouse	`cards:read`, `users:read` und `webhooks:manage` für den Ereignis-Feed
Bereitstellung von Benutzern aus Ihrem HR-System	`users:write`

Übergeben Sie die Liste beim Erstellen des Schlüssels:

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"]}'

Frühere Scopes

Schlüssel, die vor der Aufteilung der Scopes erstellt wurden, funktionieren weiter. Die Scopes read, write und admin dieser Schlüssel stehen für diese Mengen:

Früherer Scope	Bedeutet
`read`	`cards:read`, `search`, `ask`, `users:read`, `analytics:read`, `finance:read`, `catalog:read`, `files:read`
`write`	alles aus `read` sowie `cards:write`, `files:write`, `users:write`, `permissions:manage`
`admin`	jeder Scope

Ein Schlüssel, der ohne ausdrückliche Scopes erstellt wurde, erhält sie von seiner Rolle: admin erhält admin; editor und verifier erhalten write; viewer erhält read.

Scopes eines Schlüssels ansehen

GET /v1/me gibt die Scopes des Schlüssels zurück, der die Anfrage stellt – unabhängig davon, welche Scopes er hat. Bei einem Schlüssel, der ohne ausdrückliche Scopes erstellt wurde, sind das die früheren Scopes seiner Rolle, etwa read und write; die Tabelle oben zeigt, wofür sie stehen. Schlägt eine Operation mit api_keys.scope fehl, nennt error.message den fehlenden Scope.