API publique KairoProject

L'API publique KairoProject permet à vos outils et systèmes externes d'interagir directement avec vos données de pilotage : portefeuilles, projets, tâches et ressources. Ce guide couvre l'authentification, les endpoints disponibles, la gestion des webhooks sortants et les bonnes pratiques d'intégration.

Authentification

L'API utilise le flux OAuth 2.0 client_credentials. Chaque organisation peut créer des clients API depuis la console d'administration.

Créer un client API

Un owner ou admin crée un client API depuis la console. À la création, un clientId et un clientSecret sont générés — le secret n'est affiché qu'une seule fois.

Chaque client API dispose de :

• un nom affiché dans la console ;
• des scopes définissant les permissions accordées ;
• un statut (active ou revoked) ;
• une durée de vie des tokens (tokenTTLSeconds, par défaut 3 600 secondes).

Obtenir un token d'accès

POST /api/public/oauth/token

Corps de la requête :

{
  "client_id": "org123_api_acme",
  "client_secret": "kairo_sk_live_...",
  "scope": "portfolios.read projects.write"
}

Réponse :

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Utilisez ensuite le token dans toutes vos requêtes :

Authorization: Bearer <access_token>

Rotation et révocation

• Rotation : créez un nouveau secret depuis la console. L'ancien reste actif pendant une période de transition.
• Révocation : passez le client en status=revoked. Tous les nouveaux tokens sont immédiatement refusés. Pour invalider les tokens déjà émis, un champ revokedAt est vérifié côté backend.

---

Endpoints disponibles

Tous les endpoints sont préfixés par /api/public/v1 et requièrent un Bearer token valide.

Portefeuilles

Méthode	Route	Description	Scope requis
GET	/portfolios	Liste paginée des portefeuilles	portfolios.read
POST	/portfolios	Crée un portefeuille	portfolios.write
GET	/portfolios/{portfolioId}	Détails d'un portefeuille	portfolios.read

Projets

Méthode	Route	Description	Scope requis
GET	/projects	Liste/filtre des projets	projects.read
POST	/projects	Crée un projet	projects.write
PATCH	/projects/{projectId}	Met à jour les métadonnées	projects.write
POST	/projects/{projectId}:recompute	Déclenche le recalcul planning	planning.trigger

Tâches et ressources

Méthode	Route	Description	Scope requis
GET / POST / PATCH	/projects/{projectId}/tasks	Gestion des tâches	tasks.read / tasks.write
GET / POST / PATCH / DELETE	/projects/{projectId}/resources	Gestion des ressources	resources.read / resources.write

Organisation et membres

Méthode	Route	Description	Scope requis
GET	/organization	Infos plan, sièges, statut	organization.read
GET / POST / PATCH	/members	Lister, inviter, désactiver des membres	members.manage

---

Pagination et filtrage

Les listes utilisent un système de pagination par curseur.

• pageSize : nombre d'éléments par page (entre 1 et 100).
• pageToken : token de page suivante (encodé en base64), renvoyé dans nextPageToken.

Les projets acceptent des filtres supplémentaires : portfolioId, status, updatedAfter.

---

Idempotence

Pour les créations sensibles (import de projets par exemple), ajoutez un header Idempotency-Key à votre requête. Si la même clé est envoyée plusieurs fois, la réponse de la première requête est renvoyée sans créer de doublon.

---

Webhooks sortants

KairoProject peut notifier vos systèmes en temps réel via des webhooks HTTP.

Configurer un webhook

POST /api/public/v1/webhooks

Scope requis : webhooks.manage.

Chaque webhook associe :

• une URL HTTPS de destination ;
• une liste d'événements à écouter ;
• un secret de signature généré automatiquement.

Événements disponibles

Événement	Description
planning.recompute.completed	Recalcul planning terminé. Inclut bufferConsumption, progress, status.
planning.buffer_overflow	Le buffer dépasse le seuil critique (1.0). Inclut threshold et exceededAt.

Vérifier la signature

Chaque livraison inclut le header :

X-Kairo-Signature: t=<unix>,v1=<digest>

Le digest est calculé ainsi : HMAC-SHA256(secret, "${t}.${body}").

Vérifiez systématiquement cette signature côté serveur pour authentifier l'origine de l'événement.

Rotation du secret webhook

Utilisez POST /api/public/v1/webhooks/{id}/rotate-secret pour renouveler le secret de signature d'un webhook.

---

Scopes disponibles

Scope	Accès accordé
portfolios.read	Lecture des portefeuilles
portfolios.write	Création et modification des portefeuilles
projects.read	Lecture des projets
projects.write	Création et modification des projets
tasks.read	Lecture des tâches
tasks.write	Création et modification des tâches
resources.read	Lecture des ressources
resources.write	Gestion des ressources
planning.trigger	Déclenchement du recalcul planning
organization.read	Lecture des informations organisation
members.manage	Gestion des membres
webhooks.manage	Gestion des webhooks

---