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.

Modèle conceptuel

L'API suit strictement la hiérarchie de données de KairoProject :

Organisation
├── API Clients           ← vos intégrations (credentials)
├── Membres               ← utilisateurs de l'org
├── Webhooks              ← endpoints de livraison d'événements
└── Portfolio
      ├── Ressource        ← partagée entre tous les projets du portfolio
      ├── Équipe           ← groupe de ressources, partagée
      └── Projet
            ├── Tâche Root     ← tâche structurelle (non supprimable)
            ├── Tâche ...      ← vos tâches opérationnelles
            └── Tâche Finish   ← tâche structurelle (non supprimable)

Points clés à retenir :

• Toutes les données sont strictement isolées par organisation — un token ne peut jamais accéder aux données d'une autre organisation.
• Les ressources et équipes sont au niveau portfolio, partagées entre tous les projets.
• Chaque projet contient deux tâches structurelles (root, finish) qui ne peuvent pas être supprimées via l'API.
• Le recalcul CCPM (chaîne critique, tampon) est déclenché via POST /projects/{projectId}/recompute?portfolioId=... et retourne une réponse synchrone.

Base URL

https://kairoproject.app/api/public/v1

Toutes les dates sont en ISO 8601 UTC (2026-05-17T10:00:00.000Z).

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": "org_acme-api-1234",
  "client_secret": "kairo_sk_live_...",
  "scope": "projects.read tasks.write"
}

Réponse :

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "projects.read tasks.write"
}

Utilisez ensuite le token dans toutes vos requêtes :

Authorization: Bearer <access_token>

Scopes disponibles

Rotation et révocation

• Rotation : créez un nouveau secret depuis la console. Le nouveau secret devient actif immédiatement et l'ancien secret est désactivé lors de la rotation.
• Révocation : passez le client en statut révoqué depuis la console (section API). Les nouvelles demandes de token sont refusées immédiatement, et les tokens existants peuvent aussi être invalidés dès la révocation.

Rate limiting

Chaque requête authentifiée est comptabilisée dans une fenêtre glissante par client API. Les limites varient selon le scope le plus restrictif de la requête.

Chaque réponse de succès inclut les headers suivants :

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1747476120

En cas de dépassement, l'API retourne un 429 avec un corps JSON uniforme de la forme { "error": "..." }. Selon l'endpoint, des informations de délai de réessai peuvent aussi être exposées via les headers.

Endpoints disponibles

Tous les endpoints sont préfixés par /api/public/v1 et requièrent un Bearer token valide. portfolioId est toujours requis en query param pour les sous-ressources d'un portfolio.

Légende : ✅ Idempotent (répéter la requête produit le même résultat) — ❌ Crée un doublon

Portefeuilles

Champs modifiables (PATCH) : name, description, aiAssistEnabled.

Projets

Tâches

La mise à jour de ettcHours (heures restantes estimées) est le mécanisme de saisie d'avancement. Les tâches root et finish ne peuvent pas être supprimées (retourne 422).

Ressources et équipes

Les ressources et équipes sont stockées au niveau portfolio. Le projectId dans l'URL sert uniquement à déclencher un recalcul du projet concerné après mutation.

Organisation et membres

POST /members accepte deux modes : avec uid (ajoute un utilisateur existant, retourne 200) ou avec email sans uid (crée une invitation, retourne 201).

Pagination

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

• pageSize : nombre d'éléments par page (défaut 25, max 100).
• pageToken : curseur retourné dans nextPageToken par la réponse précédente.

async function fetchAllProjects(token: string, portfolioId: string) {
  const projects = [];
  let pageToken: string | null = null;
  do {
    const url = new URL("https://kairoproject.app/api/public/v1/projects");
    url.searchParams.set("portfolioId", portfolioId);
    url.searchParams.set("pageSize", "100");
    if (pageToken) url.searchParams.set("pageToken", pageToken);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
    const data = await res.json();
    projects.push(...data.items);
    pageToken = data.nextPageToken;
  } while (pageToken);
  return projects;
}

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é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}").

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyKairoSignature(
  signingSecret: string,
  signatureHeader: string,
  rawBody: string
): boolean {
  const match = signatureHeader.match(/t=([^,]+),v1=([a-f0-9]+)/);
  if (!match) return false;
  const [, timestamp, signature] = match;
  const payload = `${timestamp}.${rawBody}`;
  const expected = createHmac("sha256", signingSecret).update(payload).digest("hex");
  return timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(signature, "hex"));
}

Ignorez les livraisons avec un timestamp antérieur de plus de 5 minutes pour vous protéger des attaques replay.

Rotation du secret webhook

Utilisez POST /api/public/v1/webhooks/{id}/rotate-secret pour renouveler le secret de signature d'un webhook. L'ancienne valeur est révoquée dès la rotation.

Codes d'erreur

Toutes les erreurs retournent un corps JSON uniforme : { "error": "Description explicite du problème." }