Navin APIs

Navin exposes two JSON REST APIs over HTTPS. The Control Plane API is the single entry point of the platform: the portal, the SDKs, the CLI and the Navin Manager all go through it. The Navin Manager API drives the infrastructure: clusters, hosts, agents, services, operations, backups and the vault. This page explains the common rules and the first call; the references describe every route, parameter and field, in English and in French.

API	Prefix	Authentication	Reference	OpenAPI document
Control Plane	/v1	OIDC token (Keycloak), portal session or API key	Control Plane API reference	English - French
Navin Manager	/api/v1	Session cookie with a CSRF header, or a personal API token	Navin Manager API reference	English - French

tip

To build an application, prefer the SDKs (Python, TypeScript, Go, Java): they handle authentication, retries, pagination and typed errors for you.

Make a first call to the Control Plane

1. Get a token. Sign in to the portal (Keycloak SSO) or ask your administrator for a project API key. The tenant of the call always comes from the token, never from the request body.

2. Call a read route. Replace <token> with your token and <control-plane-host> with the address your administrator published:

   curl -H "Authorization: Bearer <token>" <control-plane-url>/v1/projects

   With an API key, send the X-API-Key: eai_... header instead.

3. Read the response. A list answers {"items": [...], "next_cursor": ...}. A 401 code means a missing, expired or invalid token; a 403 forbidden code means a missing role, with the expected roles in details.required_roles.

Make a first call to the Navin Manager

1. Create a personal API token. In the console, open your profile, then its tokens section. The token (nmt_<12 hex>_<secret>) is shown once, expires (90 days by default, at most 365) and can be restricted to a subset of your permissions.

2. Call a read route:

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

3. From a browser, the console uses an nm_session session cookie: every request that changes something (POST, PUT, PATCH, DELETE) must then carry the X-CSRF-Token header, else it is refused with 403 csrf_invalid. An API token does not need this header.

Common rules

Topic	Control Plane	Navin Manager
Format	JSON in UTF-8; file uploads in multipart/form-data; streams in Server-Sent Events or WebSocket	JSON in UTF-8
Dates	ISO 8601 in UTC	ISO 8601 with a time zone
Language of messages	Accept-Language header (en or fr)	nm_lang cookie, then the Accept-Language header
Pagination	limit (50 by default, at most 500) and cursor; read next_cursor until it is null	limit and cursor on paginated lists; next_cursor is null on the last page
Long operations	Operation-Id and Operation-Location headers, followed with GET /v1/operations/{operation_id}	{"operation_id": ...} answer, followed with GET /api/v1/operations/{operation_id} and its tasks per host
Safe retry	Idempotency-Key header (1 to 200 characters)	Validation first (.../validate), then a retry (.../retry) of a failed operation
Correlation	X-Request-Id and traceparent headers (W3C Trace Context)	Operation identifier and audit trail

Errors

Both APIs always answer with the same envelope. Test code, which never changes, and not the message: message is in the language of the caller, message_i18n gives both languages and details the machine readable context.

{
  "error": {
    "code": "forbidden",
    "message": "You do not have the required role for this operation.",
    "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"]}
  }
}

The Control Plane adds request_id, the identifier to give to support. The codes of each route are listed in the references.

Compatibility

Inside a major version, the contract only grows: new routes, new optional fields and new enumeration values may appear at any time. Ignore the fields you do not know. Removing a route or a response field, or adding a required field, needs a new major version of the contract (info.x-contract-version for the Control Plane, the /api/v1 prefix for the Navin Manager).

Go further

• Control Plane API reference: every route, with its roles, parameters, bodies and error codes.
• Navin Manager API reference: every route of the administration console.
• Control Plane API v1 contract and main architecture contracts.
• Platform API reference guide.
• SDKs and CLI.