Ambiti delle chiavi
Un ambito indica una parte dell’API che una chiave può chiamare. Ogni endpoint del riferimento API
dichiara l’unico ambito di cui ha bisogno. Una richiesta con una chiave che non lo ha viene rifiutata con 403 e il
codice api_keys.scope, prima che venga letto o modificato qualsiasi dato.
Gli ambiti dicono quali operazioni può chiamare una chiave. Il ruolo, il profilo dati e le raccolte della chiave
decidono comunque quali oggetti vedono quelle operazioni: una chiave con cards:write e il ruolo viewer non può
modificare le schede, e una chiave limitata a una raccolta non vede le altre.
Ambiti
| Ambito | Consente |
|---|---|
cards:read | Leggere schede, raccolte e cartelle. |
cards:write | Creare, modificare ed eliminare schede, raccolte e cartelle. |
search | Cercare nella knowledge base (POST /v1/search). |
ask | Fare domande all’assistente (POST /v1/ask, POST /v1/chat). |
import:write | Scrivere nelle fonti personalizzate dell’organizzazione: sincronizzazioni, batch ed eliminazioni, e leggerne lo stato. Per creare una fonte e le sue chiavi serve admin. |
webhooks:manage | Gestire i webhook e leggere il feed degli eventi (GET /v1/webhook-events). Per entrambe le cose serve anche il ruolo admin. |
users:read | Leggere utenti e gruppi. |
users:write | Modificare utenti e gruppi. |
analytics:read | Leggere le analisi. |
audit:read | Leggere il registro di audit. |
finance:read | Leggere report finanziari, fatture e pagamenti. |
catalog:read | Leggere il catalogo dei servizi. |
files:read | Leggere i file generati, come le risposte esportate. |
files:write | Modificare ed eliminare i file generati. |
permissions:manage | Concedere e revocare permessi sugli oggetti. |
admin | Le impostazioni dell’organizzazione e le sue chiavi API. Una chiave con admin ha anche tutti gli altri ambiti. |
La ricerca e le domande sono, per loro natura, letture: una chiave che può solo leggere può comunque cercare e fare domande.
Scegliere gli ambiti
Concedi gli ambiti che un’integrazione usa e nient’altro:
| Integrazione | Ambiti |
|---|---|
| Bot di domande e risposte in uno strumento di chat | search, ask |
| Importazione dal tuo sistema documentale | cards:write (API delle schede) o import:write (fonte personalizzata) |
| Esportazione in un data warehouse | cards:read, users:read e webhooks:manage per il feed degli eventi |
| Provisioning degli utenti dal tuo sistema HR | users:write |
Passa l’elenco quando crei la chiave:
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"]}'Ambiti precedenti
Le chiavi create prima della suddivisione degli ambiti continuano a funzionare. I loro ambiti read, write e
admin corrispondono a questi insiemi:
| Ambito precedente | Significa |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | tutto ciò che è in read, più cards:write, files:write, users:write, permissions:manage |
admin | tutti gli ambiti |
Una chiave creata senza ambiti espliciti li riceve dal suo ruolo: admin riceve admin; editor e verifier
ricevono write; viewer riceve read.
Vedere gli ambiti di una chiave
GET /v1/me restituisce gli ambiti della chiave che fa la richiesta, qualunque siano i suoi
ambiti. Per una chiave creata senza ambiti espliciti, sono gli ambiti precedenti del suo ruolo, come read e write;
la tabella sopra mostra a cosa corrispondono. Quando un’operazione non riesce con api_keys.scope, error.message
indica l’ambito mancante.