Authentification

Chaque requête adressée à l’API Sursa porte une clé API, ou un jeton d’accès OAuth d’une application, dans l’en-tête Authorization :

Authorization: Bearer kb_3f9c…

La clé identifie l’organisation et détermine ce que la requête peut voir et modifier : son rôle, ses portées, son profil de données et ses collections. L’adresse de l’API ne connaît ni sessions ni cookies. Chaque requête est authentifiée indépendamment : vous pouvez donc envoyer des requêtes en parallèle et depuis plusieurs serveurs avec la même clé.

curl https://api.sursa.com/v1/me \
  -H "Authorization: Bearer $SURSA_API_KEY"

Les intégrations plus anciennes envoient parfois la clé dans un en-tête X-API-Key. Il est toujours accepté, mais le nouveau code doit utiliser Authorization: Bearer.

Types d’identifiants

Identifiant	Forme	Où il fonctionne
Clé API de l’organisation	`kb_…`	Tous les points de terminaison de l’API, dans les limites de son rôle, de ses portées, de son profil de données et de ses collections.
Clé de source personnalisée	`kbsrc_…`	Uniquement les points de terminaison d’envoi (push) de sa propre source personnalisée (`/v1/push/sources/{source_id}/…`).
Jeton d’accès OAuth	`kbat_…`	Les points de terminaison de la référence de l’API, dans les limites des portées du jeton. Un jeton obtenu par `POST /oauth/token` avec un code d’autorisation agit au nom du salarié qui a donné son consentement ; un jeton `client_credentials` agit pour l’organisation, comme une clé API. Il est valable 1 heure.

Tous s’envoient de la même façon. Une clé de source personnalisée ne peut rien lire, rechercher ni modifier en dehors de sa source : utilisez-la là où la clé est conservée par un tiers, par exemple une plateforme d’intégration.

Erreurs d’authentification

Statut et code	Signification	Que faire
`401` `auth.not_authenticated`	Clé absente, mal saisie ou révoquée.	Vérifiez l’en-tête et la valeur de la clé.
`401` `api_keys.expired`	La clé a dépassé sa date d’expiration.	Créez une nouvelle clé et remplacez l’ancienne.
`401` `sources.push_key_invalid`	Une clé de source personnalisée est erronée, révoquée ou appartient à une autre source.	Vérifiez la clé et l’identifiant de la source dans le chemin.
`401` `oauth.token_expired`	Le jeton d’accès OAuth a expiré.	Obtenez-en un nouveau avec le jeton d’actualisation.
`403` `api_keys.scope`	La clé n’a pas de portée pour cette opération.	Ajoutez la portée ou utilisez une clé qui la possède.
`403` `api_keys.feature_disabled`	L’offre de l’organisation n’inclut pas les clés API.	Contactez l’administrateur de l’organisation.
`403` `api_keys.ip_not_allowed`	La requête provient d’une adresse en dehors des adresses autorisées de la clé.	Appelez depuis un réseau autorisé ou modifiez les adresses de la clé.
`403` `api_keys.mcp_only`	Une clé MCP personnelle a été utilisée en dehors du point de terminaison `/mcp`.	Utilisez une clé API de l’organisation pour l’API.
`403` `oauth.operation_not_allowed`	L’opération ne fait pas partie de l’API publique : un jeton OAuth ne peut donc pas l’appeler.	Utilisez une opération de la référence de l’API.
`403` `org.suspended`	L’organisation est suspendue. Ses données sont conservées.	Contactez l’administrateur de l’organisation.

403 signifie que la requête a été authentifiée, mais n’est pas autorisée. Un objet que la clé n’a pas le droit de voir répond 404, comme un objet qui n’existe pas : une clé ne peut donc pas découvrir ce qui se trouve hors de son accès.

Agir avec un profil de données

Une clé dotée du rôle admin peut vérifier ce que verrait un autre groupe de personnes : l’en-tête X-View-As exécute une requête avec un profil de données et, éventuellement, un rôle.

curl "https://api.sursa.com/v1/cards?limit=20" \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "X-View-As: employee:viewer"

Dans ce mode, les requêtes ne font que lire : toute modification renvoie 403 avec le code view_as.read_only. Un jeton OAuth, ou une clé sans le rôle admin, ne peut pas utiliser X-View-As : la requête répond 403 avec le code view_as.admin_key_required. Un en-tête qui ne désigne aucun profil existant répond 400 avec le code view_as.invalid_header.

Applications dans le navigateur

L’API accepte les requêtes de n’importe quelle origine web (Access-Control-Allow-Origin: *) et n’utilise jamais de cookies : une page peut donc l’appeler avec fetch. La clé se trouve alors dans la page et elle est visible de toute personne qui l’utilise. N’appelez l’API depuis le navigateur qu’avec une clé que vous acceptez de montrer à ces utilisateurs, par exemple une clé viewer limitée aux collections publiques, ou placez votre propre serveur entre le navigateur et Sursa.

Ce que seul un salarié peut faire

Une clé API de l’organisation agit pour l’organisation, pas pour une personne. Deux parties de l’API appartiennent à des personnes : elles ne fonctionnent donc qu’avec un jeton qui agit au nom d’un salarié, c’est-à-dire une session dans Sursa ou un jeton d’accès OAuth émis avec le consentement du salarié.

Les conversations appartiennent à une personne. Dans GET /v1/conversations, une clé API de l’organisation ne voit que les conversations qu’elle a elle-même commencées. L’API publique n’a aucune opération qui commence une conversation : pour une clé, la liste est donc normalement vide, et les conversations des salariés ne lui sont jamais montrées. Les questions sans conversation, avec POST /v1/ask ou POST /v1/chat, fonctionnent avec toute clé qui a la portée ask. Pour lister les conversations d’un salarié et lire l’historique de l’une d’elles avec GET /v1/conversations/{conv_id}, appelez l’API avec un jeton OAuth au nom de ce salarié. Le jeton ne voit que les conversations de ce salarié ; toute autre conversation répond 404 avec le code conversations.not_found.

Seul un salarié valide une fiche. La validation confirme qu’une personne a vérifié le contenu : POST /v1/cards/{card_id}/verification/verify et POST /v1/cards/{card_id}/verify exigent donc une session ou un jeton OAuth au nom d’un salarié autorisé à valider la fiche. Avec une clé API de l’organisation, ou un jeton client_credentials, ils répondent 400 avec le code cards.verify_user_account_required. Les contrôles habituels passent en premier : une fiche que la clé ne peut pas voir répond 404, et une clé qui n’a pas le droit de la valider reçoit 403.