Portées des clés
Une portée désigne une partie de l’API qu’une clé peut appeler. Chaque point de terminaison de la
référence de l’API déclare l’unique portée dont il a besoin. Une requête faite avec une clé qui n’a pas
cette portée est refusée avec 403 et le code api_keys.scope, avant toute lecture ou
modification.
Les portées indiquent quelles opérations une clé peut appeler. Le rôle, le profil de données et les collections de la
clé déterminent toujours quels objets ces opérations voient : une clé dotée de cards:write et du rôle viewer ne
peut pas modifier de fiches, et une clé limitée à une collection ne voit pas les autres.
Portées
| Portée | Autorise |
|---|---|
cards:read | Lire les fiches, les collections et les dossiers. |
cards:write | Créer, modifier et supprimer les fiches, les collections et les dossiers. |
search | Lancer des recherches dans la base de connaissances (POST /v1/search). |
ask | Poser des questions à l’assistant (POST /v1/ask, POST /v1/chat). |
import:write | Écrire dans les sources personnalisées de l’organisation : synchronisations, lots et suppressions, et lire leur état. La création d’une source et de ses clés exige admin. |
webhooks:manage | Gérer les webhooks et lire le flux d’événements (GET /v1/webhook-events). Les deux exigent aussi le rôle admin. |
users:read | Lire les utilisateurs et les groupes. |
users:write | Modifier les utilisateurs et les groupes. |
analytics:read | Lire les analyses. |
audit:read | Lire le journal d’audit. |
finance:read | Lire les rapports financiers, les factures et les paiements. |
catalog:read | Lire le catalogue de services. |
files:read | Lire les fichiers générés, comme les réponses exportées. |
files:write | Modifier et supprimer les fichiers générés. |
permissions:manage | Attribuer et retirer des permissions sur les objets. |
admin | Les paramètres de l’organisation et ses clés API. Une clé dotée de admin possède aussi toutes les autres portées. |
Par leur nature, la recherche et les questions sont des lectures : une clé qui ne peut que lire peut tout de même lancer des recherches et poser des questions.
Choisir les portées
Accordez les portées qu’une intégration utilise, et rien de plus :
| Intégration | Portées |
|---|---|
| Bot de questions-réponses dans un outil de messagerie | search, ask |
| Import depuis votre système documentaire | cards:write (API des fiches) ou import:write (source personnalisée) |
| Export vers un entrepôt de données | cards:read, users:read et webhooks:manage pour le flux d’événements |
| Provisionnement des utilisateurs depuis votre SIRH | users:write |
Passez la liste lors de la création de la clé :
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"]}'Anciennes portées
Les clés créées avant la division des portées continuent de fonctionner. Leurs portées read, write et admin
correspondent aux ensembles suivants :
| Ancienne portée | Signifie |
|---|---|
read | cards:read, search, ask, users:read, analytics:read, finance:read, catalog:read, files:read |
write | tout ce que contient read, plus cards:write, files:write, users:write, permissions:manage |
admin | toutes les portées |
Une clé créée sans portées explicites les reçoit de son rôle : admin reçoit admin ; editor et verifier
reçoivent write ; viewer reçoit read.
Voir les portées d’une clé
GET /v1/me renvoie les portées de la clé qui fait la requête, quelles que soient ses
portées. Pour une clé créée sans portées explicites, ce sont les anciennes portées de son rôle, comme read et
write ; le tableau ci-dessus indique ce qu’elles recouvrent. Quand une opération échoue avec api_keys.scope,
error.message nomme la portée qui manquait.