API de Navin

Navin expose deux API REST en JSON sur HTTPS. L'API du Control Plane est le point d'entrée unique de la plateforme : le portail, les SDK, la CLI et le Navin Manager passent tous par elle. L'API du Navin Manager pilote l'infrastructure : clusters, machines, agents, services, opérations, sauvegardes et coffre-fort. Cette page explique les règles communes et le premier appel ; les références détaillent chaque route, chaque paramètre et chaque champ, en français et en anglais.

API	Préfixe	Authentification	Référence	Document OpenAPI
Control Plane	`/v1`	Jeton OIDC (Keycloak), session du portail ou clé d'API	Référence de l'API du Control Plane	Français - anglais
Navin Manager	`/api/v1`	Cookie de session avec en-tête CSRF, ou jeton d'API personnel	Référence de l'API du Navin Manager	Français - anglais

astuce

Pour développer une application, préférez les SDK (Python, TypeScript, Go, Java) : ils gèrent l'authentification, les nouvelles tentatives, la pagination et les erreurs typées pour vous.

Faire un premier appel au Control Plane

Obtenir un jeton. Connectez-vous au portail (SSO Keycloak) ou demandez à votre administrateur une clé d'API de projet. Le tenant de l'appel vient toujours du jeton, jamais du corps de la requête.
Appeler une route de lecture. Remplacez <jeton> par votre jeton et <control-plane-host> par l'adresse publiée par votre administrateur :
```
curl -H "Authorization: Bearer <jeton>" <control-plane-url>/v1/projects
```
Avec une clé d'API, envoyez plutôt l'en-tête X-API-Key: eai_....
Lire la réponse. Une liste répond {"items": [...], "next_cursor": ...}. Un code 401 signale un jeton absent, expiré ou invalide ; un code 403 forbidden signale un rôle insuffisant, avec les rôles attendus dans details.required_roles.

Faire un premier appel au Navin Manager

Créer un jeton d'API personnel. Dans la console, ouvrez votre profil puis la section des jetons. Le jeton (nmt_<12 hex>_<secret>) n'est affiché qu'une fois, expire (90 jours par défaut, 365 au plus) et peut être limité à une partie de vos permissions.

Appeler une route de lecture :

curl -H "Authorization: Bearer <jeton>" https://<manager-host>/api/v1/clusters

Depuis un navigateur, la console utilise un cookie de session nm_session : chaque requête qui modifie (POST, PUT, PATCH, DELETE) doit alors porter l'en-tête X-CSRF-Token, sinon elle est refusée avec 403 csrf_invalid. Un jeton d'API n'a pas besoin de cet en-tête.

Règles communes

Sujet	Control Plane	Navin Manager
Format	JSON en UTF-8 ; envois de fichiers en `multipart/form-data` ; flux en Server-Sent Events ou WebSocket	JSON en UTF-8
Dates	ISO 8601 en UTC	ISO 8601 avec fuseau horaire
Langue des messages	En-tête `Accept-Language` (`en` ou `fr`)	Cookie `nm_lang`, puis en-tête `Accept-Language`
Pagination	`limit` (50 par défaut, 500 au plus) et `cursor` ; lisez `next_cursor` jusqu'à `null`	`limit` et `cursor` sur les listes paginées ; `next_cursor` vaut `null` sur la dernière page
Opérations longues	En-têtes `Operation-Id` et `Operation-Location`, suivi par `GET /v1/operations/{operation_id}`	Réponse `{"operation_id": ...}`, suivi par `GET /api/v1/operations/{operation_id}` et ses tâches par machine
Nouvelle tentative sûre	En-tête `Idempotency-Key` (1 à 200 caractères)	Validation préalable (`.../validate`) puis relance (`.../retry`) d'une opération échouée
Corrélation	En-têtes `X-Request-Id` et `traceparent` (W3C Trace Context)	Identifiant d'opération et journal d'audit

Erreurs

Les deux API répondent toujours avec la même enveloppe. Testez code, qui ne change jamais, et non le message : message est dans la langue de l'appelant, message_i18n donne les deux langues et details le contexte lisible par une machine.

{
  "error": {
    "code": "forbidden",
    "message": "Vous n'avez pas le rôle requis pour cette opération.",
    "message_i18n": {"en": "You do not have the required role for this operation.", "fr": "Vous n'avez pas le rôle requis pour cette opération."},
    "details": {"required_roles": ["tenant_admin"]}
  }
}

Le Control Plane ajoute request_id, l'identifiant à transmettre au support. Les codes de chaque route sont listés dans les références.

Compatibilité

Dans une version majeure, le contrat ne fait que grandir : de nouvelles routes, de nouveaux champs facultatifs et de nouvelles valeurs d'énumération peuvent apparaître à tout moment. Ignorez donc les champs que vous ne connaissez pas. Une suppression de route ou de champ de réponse, ou un nouveau champ obligatoire, exige une nouvelle version majeure du contrat (info.x-contract-version pour le Control Plane, préfixe /api/v1 pour le Navin Manager).

Aller plus loin

Référence de l'API du Control Plane : chaque route, avec ses rôles, ses paramètres, ses corps et ses codes d'erreur.
Référence de l'API du Navin Manager : chaque route de la console d'administration.
Contrat de l'API du Control Plane v1 et contrats principaux de l'architecture.
Guide de la référence API de la plateforme.
SDK et CLI.

Faire un premier appel au Control Plane​

Faire un premier appel au Navin Manager​

Règles communes​

Erreurs​

Compatibilité​

Aller plus loin​