API — Intégrations M2M V1

Cette référence décrit le contrat V1 permettant à un backend partenaire de provisionner un périmètre opaque, publier des projections métier, gérer des médias autorisés et construire ou lire un Knowledge Graph isolé.

Les schémas exhaustifs restent dans openapi.json.

Invariants de sécurité

• Authentification OIDC OAuth2 client_credentials obligatoire.
• Le principal doit être classé machine et lié au caller_app par NEXUS_M2M_CALLER_APP_CLIENTS.
• Dans le contrat actuel, source_app doit être égal à caller_app.
• nexus.ingest et can_write protègent les mutations.
• nexus.query et can_read protègent les lectures.
• external_scope_id est un UUID opaque appartenant à l'application cliente. Nexus résout seul le workspace canonique.
• Le client ne fournit jamais de tenant_id et ne choisit pas un workspace Nexus arbitraire.
• Une ressource d'un autre tenant, caller ou scope est non énumérable.

Séquence recommandée

1. Obtenir un bearer M2M à durée courte.
2. Vérifier le principal avec GET /api/auth/oidc/me.
3. Appeler POST /api/v1/integration-scopes/ensure.
4. Utiliser le même external_scope_id pour les médias, projections et routes KG workspace.
5. Réconcilier périodiquement les projections, sans lire les stores internes de Nexus.

Périmètres d'intégration

Exemple de provisioning :

{
  "caller_app": "partner_app",
  "source_app": "partner_app",
  "external_scope_id": "8e02a671-8604-49d1-9ebf-28a60475e91e",
  "projects": ["entities", "relations", "media"]
}

ensure est rejouable. Une liste de projets invalide renvoie 422. Un scope inactif ou inaccessible reste masqué par 404. L'absence de binding M2M côté Nexus renvoie 503 et doit être corrigée par un opérateur, pas contournée par le client.

Media V1

Les usages V1 sont profile et content. Les types déclarables sont exposés dans OpenAPI ; les limites opérationnelles sont contrôlées côté Nexus et résumées dans le guide API général. Le format réel est validé à partir du contenu lors du commit. expected_checksum_sha256, expected_byte_size, object_id et object_version_id empêchent de confondre deux versions.

Disponibilité actuelle

Le chemin est générique, mais l'adaptateur Media V1 actuellement livré réutilise le stockage privé Narrélia et son autorisation M2M. Il est donc exploitable par le client Narrélia autorisé. L'ouverture à une autre application nécessite une validation Nexus dédiée de son binding, de ses usages, limites et règles de stockage ; le seul changement de caller_app dans le payload ne suffit pas.

Les routes historiques /api/narrelia/media/* restent disponibles pour compatibilité. Les nouvelles intégrations ne doivent pas les utiliser.

Projections domaine

Chaque mutation utilise contract_version="1.0", command_id, idempotency_key, aggregate_version et le scope opaque. Un replay strictement identique retourne le résultat initial. Nexus renvoie notamment :

• 409 idempotency_conflict si une clé est réutilisée avec une autre commande ;
• 409 version_conflict pour une version ancienne ou incohérente ;
• 409 projection_reference_unavailable si une relation référence une entité inactive ou hors scope ;
• 404 projection_unavailable pour une projection non visible.

Une projection est une copie reconstruisible ; l'application cliente reste propriétaire de la vérité métier.

Knowledge Graph workspace

Toutes les lectures portent caller_app, source_app et external_scope_id. Nexus dérive une clé de graphe workspace ; aucune absence de graphe workspace ne retombe sur le graphe global. Une reconstruction building ou failed ne remplace pas la dernière version ready.

Le détail du modèle de graphe est dans 55-Knowledge-Graph.md.

Erreurs et reprise

Ne jamais journaliser le bearer, le secret client, les contenus médias ou les payloads métier complets. Les preuves d'intégration doivent se limiter aux IDs opaques, statuts, codes d'erreur contrôlés et identités de client non secrètes.