Authentification et clés d'API

L'API publique Kabeen authentifie chaque requête avec une clé d'API — un identifiant de type bearer lié à un espace de travail. Il n'y a ni flux OAuth, ni cookie de session, ni étape de connexion : un administrateur de l'espace de travail crée une clé une fois depuis l'application Kabeen, et vous la présentez à chaque requête.

Fonctionnement

• Une clé d'API appartient à exactement un espace de travail. L'espace de travail est lié à la clé au moment de sa création et n'est jamais passé dans le chemin, la query string ou le corps de la requête — chaque endpoint opère implicitement sur « l'espace de travail auquel cette clé appartient ».
• Une clé porte un ensemble fixe de scopes de permission (par exemple applications:read, infrastructure:edit). Chaque endpoint requiert exactement un scope, documenté dans la Référence des endpoints.
• Les clés sont créées, renouvelées et révoquées par un administrateur de l'espace de travail depuis l'application Kabeen — l'API publique elle-même n'expose aucun endpoint de gestion des clés.
• Tout le trafic de l'API publique est authentifié comme un acteur de type service (la clé), jamais comme un membre humain. Les entrées du journal d'audit correspondant aux appels de l'API publique enregistrent la clé comme acteur.

Présenter la clé

Chaque clé générée commence par le préfixe kbn_ (en pratique kbn_live_...). L'API accepte la clé via deux transports équivalents — utilisez celui qui convient le mieux à votre client HTTP :

Les deux sont reconnus par le même mécanisme d'authentification, uniquement sur les chemins sous /public/. Si les deux en-têtes sont présents, X-Api-Key est prioritaire.

curl https://app.kabeen.io/public/v1/me \
  -H "Authorization: Bearer kbn_live_51gv9c2b7f2a4e6f8c1a0d3b6e9f2c5a8"

curl https://app.kabeen.io/public/v1/me \
  -H "X-Api-Key: kbn_live_51gv9c2b7f2a4e6f8c1a0d3b6e9f2c5a8"

Introspection : GET /me

Avant de brancher quoi que ce soit d'autre, appelez GET /public/v1/me. Cet endpoint ne requiert qu'une clé valide (aucun scope particulier) et vous indique exactement à quel espace de travail vous êtes lié et ce que la clé peut faire — utile à la fois comme test de bon fonctionnement (« ma clé marche-t-elle ? ») et pour construire des intégrations qui s'adaptent aux scopes qui leur ont été accordés.

{
  "workspace": {
    "id": "3f9c9f2e-8a71-4e2a-9b0d-2c5f6a1d7e44",
    "name": "Acme Corp"
  },
  "key": {
    "id": "8b2e6a4d-1c3f-4a9e-9d7b-5f0e2c8a6b31",
    "name": "Finance integration",
    "alias": "read"
  },
  "permissions": [
    "applications:read",
    "contracts:read",
    "data:read",
    "infrastructure:read"
  ]
}

• workspace — l'espace de travail auquel la clé est liée (id + nom d'affichage).
• key — les métadonnées de la clé : id, name et alias (l'alias dont elle est issue — read, write ou admin — ou null si la clé a été créée à partir d'un ensemble de scopes explicite et personnalisé).
• permissions — la liste exacte et triée des scopes de permission accordés par cette clé. C'est la source de vérité de ce que la clé peut appeler ; considérez-la comme le contrat, pas le nom de l'alias.

Scopes de permission

Chaque endpoint requiert exactement un scope de permission, de la forme resource:action :

Alias ou scopes explicites

Une clé est délimitée d'exactement une des deux façons suivantes, choisie à sa création :

• Un alias — read, write ou admin — qui fige un instantané de l'ensemble de permissions du rôle système correspondant au moment de la création. Le champ alias de la clé (visible dans GET /me) enregistre l'alias d'origine, mais les permissions accordées sont l'instantané figé, pas un lien vivant vers le rôle : si les permissions du rôle changent par la suite, les clés existantes conservent ce qui leur a été accordé.
• Une liste explicite de codes resource:action. Dans ce cas, alias vaut null.

Dans les deux cas, une clé ne peut jamais recevoir un scope que son créateur ne détient pas personnellement au moment de la création — un administrateur ne peut pas émettre une clé plus puissante que son propre compte.

Quand un scope manque

Appeler un endpoint sans le scope requis renvoie 403 Forbidden :

{
  "code": "insufficient_permission",
  "message": "missing permission: applications:edit",
  "status": 403
}

Ne codez pas en dur d'hypothèses sur ce qu'une clé peut faire — appelez GET /me et vérifiez permissions avant de tenter un appel, ou gérez proprement 403/insufficient_permission et remontez l'information à la personne qui gère la clé de l'intégration.

Cycle de vie et gestion des clés

Les clés d'API sont créées, renouvelées et révoquées par un administrateur de l'espace de travail depuis l'application Kabeen — la gestion des clés ne fait pas partie de l'API publique elle-même. Ce à quoi vous attendre sur le plan opérationnel :

• Création — un administrateur nomme la clé et la délimite soit via un alias (read/write/admin), soit via une liste explicite de codes de permission (jamais les deux, jamais aucun des deux), avec une date d'expiration facultative. Le secret en clair n'est renvoyé qu'une seule fois, au moment de la création — Kabeen ne le stocke pas sous forme récupérable et ne peut pas vous le montrer à nouveau. Seul un hachage SHA-256 du secret est conservé ; ce que vous pouvez récupérer ensuite, ce sont des métadonnées plus un court préfixe d'affichage de la clé.
• Rotation — renouveler une clé génère un tout nouveau secret (à nouveau affiché une seule fois) et invalide immédiatement l'ancien secret, tout en conservant le même id, le même nom et les mêmes scopes.
• Révocation — une clé révoquée ou supprimée cesse de fonctionner immédiatement : chaque requête recherche la clé via le hachage de son secret et exige qu'elle soit active à cet instant, il n'y a donc aucune fenêtre de cache ni délai de propagation.
• Expiration — une clé créée avec une date d'expiration cesse d'authentifier dès que cet instant est passé, avec le même mécanisme de vérification à chaque requête, sans cache.

Cas d'échec

Les échecs d'authentification renvoient 401 Unauthorized dans tous les cas suivants :

• Aucun identifiant présenté (ni Authorization: Bearer ni X-Api-Key).
• L'identifiant ne commence pas par le préfixe kbn_ (malformé / pas une clé Kabeen).
• La clé ne correspond à aucune clé actuellement active (erronée, révoquée ou supprimée).
• La clé a dépassé sa date d'expiration.

Un véritable 401 est rejeté au niveau de la couche d'authentification, avant que le corps d'erreur uniforme de l'API puisse être attaché : la réponse a un corps vide et un en-tête WWW-Authenticate: Bearer realm="kbine", error="invalid_token". N'essayez pas d'extraire du JSON d'un 401 — voir Pagination et erreurs.

403 Forbidden est un cas d'échec distinct : la clé est valide et authentifiée, mais il lui manque le scope requis par l'endpoint.

Bonnes pratiques de sécurité

• Traitez la clé comme un secret. Quiconque la détient peut agir comme une identité de service dans votre espace de travail, dans la limite des permissions qui lui ont été accordées.
• Ne commitez jamais de clés dans le contrôle de version et ne les intégrez jamais dans du code côté client (JS navigateur, applications mobiles, dépôts publics). L'API publique est conçue pour des intégrations de serveur à serveur.
• Stockez les clés dans des variables d'environnement ou un gestionnaire de secrets, pas dans des fichiers de configuration versionnés dans un dépôt.
• Privilégiez le principe du moindre privilège. Une intégration de reporting en lecture seule devrait recevoir une clé read (ou une clé personnalisée en lecture seule), pas admin.
• Renouvelez périodiquement, et immédiatement après toute suspicion d'exposition — la rotation invalide l'ancien secret dès que le nouveau est émis.
• Révoquez les clés que vous n'utilisez plus. La révocation prend effet dès la requête suivante, révoquer rapidement n'a donc aucun coût opérationnel.
• Définissez une expiration pour les intégrations temporaires ou limitées dans le temps, plutôt que de compter sur une révocation manuelle ultérieure.