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, ressources, temps passé et bien plus. 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.

URL publique de l'API

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

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

Authentification

L'API propose deux flux OAuth 2.0 selon votre contexte d'intégration : client_credentials pour une intégration serveur-à-serveur (votre ERP détient directement le secret), et authorization_code + PKCE pour un agent qui doit obtenir le consentement explicite d'un utilisateur final sans jamais voir son mot de passe. 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, jamais dépassée quelle que soit la configuration).

Authentification serveur-à-serveur (client_credentials)

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>

Authentification par consentement utilisateur (authorization_code + PKCE)

Ce flux s'utilise quand un agent (Claude.ai, ChatGPT) doit agir au nom d'un utilisateur précis, avec son consentement explicite, sans jamais détenir son mot de passe.

1. Discovery — l'agent lit les endpoints disponibles :

   curl https://app.kairoproject.com/.well-known/oauth-authorization-server
   

2. Générer le couple PKCE (code_verifier aléatoire, code_challenge = SHA-256 encodé en base64url) :

   import { randomBytes, createHash } from "node:crypto";
   
   const codeVerifier = randomBytes(32).toString("base64url");
   const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
   

3. Ouvrir le navigateur vers l'écran de consentement :

   https://app.kairoproject.com/api/public/oauth/authorize
     ?response_type=code
     &client_id=org_demo-api-1234
     &redirect_uri=https://integrateur.example.com/callback
     &code_challenge=<codeChallenge>
     &code_challenge_method=S256
     &scope=portfolios.read+tasks.write
     &state=<valeur-aléatoire-anti-CSRF>
   

4. L'utilisateur se connecte, voit les permissions demandées et clique Autoriser. KairoProject redirige vers redirect_uri?code=<code>&state=<state> (le code expire après 10 minutes).
5. Échanger le code contre un token, avec le code_verifier généré à l'étape 2 :

   curl -X POST https://app.kairoproject.com/api/public/oauth/token \
     -H "Content-Type: application/json" \
     -d '{
       "grant_type": "authorization_code",
       "client_id": "org_demo-api-1234",
       "client_secret": "kairo_sk_...",
       "code": "<code>",
       "redirect_uri": "https://integrateur.example.com/callback",
       "code_verifier": "<codeVerifier>"
     }'
   

   Réponse identique au flux client_credentials, avec en plus un refresh_token si le scope offline_access a été demandé.

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). L'accès est coupé immédiatement : chaque requête revérifie le statut du client, y compris pour un token émis avant la révocation. Il n'y a aucun délai à attendre — un token compromis cesse de fonctionner dès la révocation, sans attendre son expiration naturelle. Après une réactivation, les tokens émis avant la révocation restent rejetés ; seuls ceux émis après la réactivation sont valides.

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, domainId (doit référencer un domaine existant de la bibliothèque Domaines & Phases, voir plus bas — 404 sinon).

Décision de priorité CCPM du portefeuille et diagnostic de la ressource stratégique (goulot au sens de la théorie des contraintes) — calculé à la demande à chaque appel, jamais mis en cache. Indique quel projet protéger en priorité et quelle ressource, si on lui ajoutait de la capacité, ferait le plus progresser l'ensemble du portefeuille. Ne couvre que les projets released: true.

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 (un chemin équivalent /portfolios/:id/resources[...] et /portfolios/:id/teams[...] existe et opère sur la même collection, sans déclencher de recalcul). Le projectId dans l'URL sert uniquement à déclencher un recalcul du projet concerné après mutation.

load-timeline retourne la courbe de charge hebdomadaire d'une ressource (heures planifiées vs capacité) — à titre indicatif : ne distingue pas les tâches co-assignées à plusieurs ressources ni les affectations via équipe.

Domaines & Phases

Référentiel partagé (indépendant d'un portfolio précis) utilisé pour catégoriser les tâches par phase et colorer le Gantt.

PATCH /domains/:id remplace name et/ou l'intégralité du tableau phases — pas un merge. Pour ajouter/modifier/retirer une seule phase sans resoumettre les autres, préférez les endpoints .../phases[/:phaseId] dédiés. DELETE /domains/:id est refusée (400) si un portfolio référence encore ce domaine. La couleur d'une phase doit appartenir à la palette autorisée (18 couleurs prédéfinies).

Clients

Un client est un tiers facturable (compte-level, jamais imbriqué sous un portfolio) — typiquement le nom/code ERP du client final d'un projet.

PATCH écrase systématiquement tout rattachement existant (l'ERP fait foi). Si clientId ne correspond à aucun client déjà créé, un nouveau client est automatiquement créé plutôt que rejeté.

Import de projet

Crée en un seul appel un projet complet (tâches, ressources, équipes, calendriers) depuis un objet kairo-project-export — pour migrer depuis un outil tiers (Jira, MS Project, Asana, Excel) ou générer un projet depuis un cahier des charges. Ré-importer avec le même externalId de projet met à jour la même ressource plutôt que d'en créer un doublon.

Timesheet

Journal des heures passées, à des fins de reporting et de calcul de coûts. Deux origines : source: "auto" (générée automatiquement à chaque PATCH .../tasks/:taskId qui modifie ettcHours) et source: "manual". Créer ou corriger une entrée ne modifie pas ettcHours sur la tâche associée et ne déclenche aucun recalcul planning.

.../adjustments corrige une entrée déjà exportée (verrouillée) sans jamais réécrire l'original — logique de note de crédit comptable. Échoue en 400 si l'entrée référencée n'est pas encore exportée (utilisez alors un PATCH normal). durationHours est signé (négatif pour retrancher, positif pour ajouter).

Causes de retard qualifiées (buffer)

Journal des causes de retard qualifiées — chaque événement correspond à une consommation de tampon CCPM imputée à une cause précise (données source du Pareto des causes de retard). categoryId: null déclasse l'événement en « Sans cause ». Renommer ou supprimer une catégorie n'affecte jamais categoryNameSnapshot sur les événements déjà qualifiés — l'historique du Pareto reste stable dans le temps.

Coûts

Calculés à partir des entrées timesheet (durationHours × hourlyRate) — jamais persistés, recalculés à chaque appel. Si aucune ressource n'a de hourlyRate défini, les champs de coût sont null plutôt que 0, pour distinguer « pas de tarif configuré » de « coût nul ».

Presets PERT et risque de retard (ML)

Les presets PERT (vitesses optimiste/médiane/pessimiste) convertissent une quantité de travail en heures avant un import ou une création de tâche. /risk retourne une probabilité de retard prédite par un modèle ML entraîné sur l'historique de l'organisation (horizonDays, défaut 7, borné entre 7 et 21) ; source: "fallback" signifie qu'aucun modèle entraîné n'est disponible pour ce périmètre.

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://app.kairoproject.com/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.

OpenAPI et génération de SDK

Le contrat technique complet de l'API est disponible au format OpenAPI 3.1. Deux usages principaux :

• Publier la spec pour vos équipes ou partenaires intégrateurs.
• Générer un SDK typé plutôt qu'écrire les appels HTTP à la main :

  npx openapi-typescript docs/api/public-api-openapi.yaml --output sdk/public-api.ts
  

  Le fichier généré expose les types (Portfolio, Resource, Member, etc.) et peut être publié dans un package interne.

Pour d'autres langages, openapi-generator-cli peut partir de la même spec :

openapi-generator-cli generate -i docs/api/public-api-openapi.yaml -g go

Codes d'erreur

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