API publique v1, serveur MCP et CLI — brancher POSITRONIA dans vos outils

En une phrase

L'Audit SaaS par URL de POSITRONIA est pilotable par trois surfaces machine — API REST v1, serveur MCP hébergé, CLI positronia — avec les mêmes quotas et le même scellement que depuis votre Espace Client.

Spécification machine : /openapi.json (OpenAPI 3.1).

Quelle surface pour quel usage ?

Les trois surfaces sont incluses dans votre abonnement (aucun coût additionnel) et wrappent le même moteur : une seule clé etia_, un seul compteur de quotas, un même rapport scellé.

L'installation des outils est libre et gratuite (npm public, doc ouverte) ; l'exécution d'un audit demande une clé API, donc un abonnement actif — c'est l'audit qui a de la valeur, pas le tuyau.

Authentification

1. Dans votre Espace Client, ouvrez Sentinel → API publique et créez une clé (nommez-la par usage : « CI production », « agent conformité »…).
2. Copiez le secret immédiatement : il n'est affiché qu'une seule fois — seule son empreinte SHA-256 est conservée côté serveur. En cas de perte, révoquez la clé et créez-en une nouvelle.
3. Passez la clé dans l'en-tête de chaque requête :

Authorization: Bearer etia_…

Une clé permet de lancer et lire des audits, jamais de gérer le compte ni de créer d'autres clés (la gestion des clés reste réservée à la session web). Limite : 10 clés actives par compte, 5 requêtes d'audit/minute par clé.

Lancer un audit SaaS

curl -X POST https://app.eutrustedia.eu/api/v1/audits/saas \
  -H "Authorization: Bearer etia_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://exemple-saas.com",
    "useCase": "Messagerie interne RH",
    "dataSensitivity": "professional",
    "position": "responsable de traitement"
  }'

Réponse (audit créé) :

{ "id": "cm…", "verdict": "…", "sealedHash": "…" }

Si votre compte a déjà audité ce domaine, l'API renvoie l'existant sans consommer de quota ("code": "ALREADY_AUDITED" + existingId). Passez "force": true pour relancer une analyse à jour (consomme 1 audit).

Champs : dataSensitivity ∈ public | professional | rgpd_art9 | oiv · computeRegions (optionnel, déclaratif) · force (optionnel).

Lire les résultats

# Liste (50 plus récents, métadonnées seules)
curl https://app.eutrustedia.eu/api/v1/audits/saas \
  -H "Authorization: Bearer etia_…"

# Détail — rapport markdown complet + hash de scellement + attestations
curl https://app.eutrustedia.eu/api/v1/audits/saas/AUDIT_ID \
  -H "Authorization: Bearer etia_…"

Le rapport détaillé porte le même scellement cryptographique (hash chaîné, signature Ed25519) que dans l'Espace Client, et les recommandations générées avec assistance IA portent le marquage AI Act Article 50.

Quotas et codes d'erreur

Les audits lancés par API décomptent le même quota que ceux lancés depuis l'Espace Client (SOLO 10/mois · GENESIS 30/mois · AVANTAGES et ENTREPRISE illimités) — l'API n'est pas un contournement.

Les codes sont contractuels (stables sur /api/v1) ; les messages texte peuvent évoluer.

Serveur MCP (agents IA, IDE, terminaux)

POSITRONIA expose un serveur MCP hébergé (Model Context Protocol, transport HTTP streamable) — branchez vos audits directement dans Claude Code, Cursor ou tout client MCP, avec la même clé API :

claude mcp add --transport http positronia https://app.eutrustedia.eu/api/mcp \
  --header "Authorization: Bearer etia_…"

3 outils exposés : run_saas_audit (lancer un audit par URL), get_saas_audit (rapport complet), list_saas_audits (historique). Mêmes quotas, mêmes gates, même scellement que l'API v1 — le MCP ne contourne rien.

CLI positronia (terminal)

La CLI officielle est publiée sur le registre npm — zéro dépendance, zéro script d'installation (7 ko : un wrapper de l'API v1, rien d'autre) :

npx positronia --help          # sans installation
npm i -g positronia            # ou pnpm add -g / bun add -g

La clé est lue uniquement depuis l'environnement (jamais en argument — l'historique du shell fuite) :

export ETIA_API_KEY=etia_…

# Auditer un SaaS (cache-first par domaine, --force pour relancer)
positronia audit https://exemple-saas.com \
  --use-case "Messagerie interne RH" \
  --position "responsable de traitement" \
  --sensitivity professional

# Historique, détail, export du rapport markdown
positronia list
positronia get AUDIT_ID
positronia get AUDIT_ID --md > rapport.md

Sortie : table lisible sur un terminal interactif, JSON dès que la sortie est pipée (ou --json) — scripts et agents n'ont rien à parser de fragile. Codes de sortie contractuels : 0 succès · 1 erreur API (le code ci-dessus est affiché) · 2 erreur d'usage ou de configuration.

---

Cadre d'utilisation : l'usage des trois surfaces (API v1, MCP, CLI) est encadré par les Conditions d'utilisation des accès programmatiques — clé personnelle, quotas partagés avec votre plan, licence MIT du CLI distincte du droit d'accès au service.