Àmbits de les claus
Un àmbit designa una part de l’API que una clau pot cridar. Cada punt final de la referència de l’API
declara l’únic àmbit que necessita. Una sol·licitud amb una clau que no el té es rebutja amb 403 i el codi
api_keys.scope, abans de llegir o canviar res.
Els àmbits diuen quines operacions pot cridar una clau. El rol, el perfil de dades i les col·leccions de la clau
continuen decidint quins objectes veuen aquestes operacions: una clau amb cards:write i el rol viewer no pot
canviar entrades, i una clau limitada a una col·lecció no veu les altres.
Àmbits
| Àmbit | Permet |
|---|---|
cards:read | Llegir entrades, col·leccions i carpetes. |
cards:write | Crear, canviar i eliminar entrades, col·leccions i carpetes. |
search | Cercar a la base de coneixement (POST /v1/search). |
ask | Fer preguntes a l’assistent (POST /v1/ask, POST /v1/chat). |
import:write | Escriure a les fonts personalitzades de l’organització: sincronitzacions, lots i eliminacions, i llegir-ne l’estat. Per crear una font i les seves claus cal admin. |
webhooks:manage | Gestionar els webhooks i llegir el canal d’esdeveniments (GET /v1/webhook-events). Totes dues coses també necessiten el rol admin. |
users:read | Llegir usuaris i grups. |
users:write | Canviar usuaris i grups. |
analytics:read | Llegir les analítiques. |
audit:read | Llegir el registre d’auditoria. |
finance:read | Llegir informes financers, factures i pagaments. |
catalog:read | Llegir el catàleg de serveis. |
files:read | Llegir els fitxers generats, com ara les respostes exportades. |
files:write | Canviar i eliminar els fitxers generats. |
permissions:manage | Concedir i revocar permisos sobre objectes. |
admin | La configuració de l’organització i les seves claus d’API. Una clau amb admin també té tots els altres àmbits. |
Pel seu significat, la cerca i les preguntes són lectures: una clau que només pot llegir també pot cercar i fer preguntes.
Triar els àmbits
Concediu els àmbits que fa servir una integració i res més:
| Integració | Àmbits |
|---|---|
| Bot de preguntes i respostes en una eina de xat | search, ask |
| Importació des del vostre sistema de documents | cards:write (API d’entrades) o import:write (font personalitzada) |
| Exportació a un magatzem de dades | cards:read, users:read i webhooks:manage per al canal d’esdeveniments |
| Alta d’usuaris des del vostre sistema de recursos humans | users:write |
Passeu la llista quan creeu la clau:
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"]}'Àmbits anteriors
Les claus creades abans que es dividissin els àmbits continuen funcionant. Els seus àmbits read, write i admin
equivalen a aquests conjunts:
| Àmbit anterior | Equival a |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | tot el de read, més cards:write, files:write, users:write, permissions:manage |
admin | tots els àmbits |
Una clau creada sense àmbits explícits els rep del seu rol: admin rep admin; editor i verifier reben write;
viewer rep read.
Consultar els àmbits d’una clau
GET /v1/me retorna els àmbits de la clau que fa la sol·licitud, sigui quin sigui el seu
conjunt d’àmbits. En una clau creada sense àmbits explícits, són els àmbits anteriors del seu rol, com ara read i
write; la taula de dalt mostra què volen dir. Quan una operació falla amb api_keys.scope, error.message indica
l’àmbit que faltava.