CONFORVA API

Une décision avant l'exécution.

Conforva permet à votre application d'envoyer une action d'agent vers une couche de contrôle avant son exécution. L'API s'authentifie avec une clé liée à votre organisation et renvoie une décision, le contexte de risque, le résultat des règles et les vérifications applicables.

Chemin de base : /api/v1 Les clés API sont créées depuis votre compte Conforva.

Démarrage rapide

1. Créez un compte. 2. Créez un agent dans le tableau de bord. 3. Créez une clé API. 4. Conservez-la côté serveur. 5. Appelez l'endpoint d'évaluation juste avant l'exécution de votre action.

curl -X POST https://conforva.com/api/v1/actions/evaluate \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "finance-prod",
    "action_type": "transfer",
    "amount": 2000,
    "parameters": {"currency": "EUR"},
    "description": "Virement demandé par l'agent finance"
  }'

Votre application doit appliquer la valeur decision avant d'exécuter l'action.

Authentification

Les appels API client utilisent une clé API dans l'en-tête Bearer. Les clés sont liées à une organisation et ne doivent jamais être exposées dans le navigateur, une application mobile ou un dépôt public.

Authorization: Bearer cv_live_...

Conservez la clé dans un gestionnaire de secrets ou une variable d'environnement côté serveur. Une clé inconnue ou révoquée renvoie 401.

Évaluer une action

POST/api/v1/actions/evaluate

{
  "agent_id": "finance-prod",
  "action_type": "transfer",
  "amount": 2000,
  "parameters": {
    "currency": "EUR"
  },
  "description": "Virement demandé par l'agent finance"
}

Champs de la requête

Champ	Obligatoire	Type	Description
agent_id	Oui	string	Agent configuré dans la même organisation Conforva.
action_type	Oui	string	Catégorie d'action utilisée par les contrôles de risque et de règles.
amount	Non	number\|null	Montant numérique facultatif utilisé par les contrôles.
parameters	Non	object\|null	Paramètres de l'action évalués par les contrôles configurés.
description	Non	string	Contexte lisible fourni avec la demande.

Ordre de traitement

Authentification de la clé et rattachement à son organisation.
Chargement de l'agent et des règles actives.
Évaluation du niveau de risque et des facteurs associés.
Application des contrôles déterministes.
Si une règle déterministe bloque l'action, elle est arrêtée à cette étape.
Sinon, une vérification supplémentaire peut analyser l'action et son contexte.
La décision et l'événement d'utilisation sont enregistrés pour l'organisation.

Réponse

L'endpoint renvoie du JSON. Les décisions actuelles sont approved ou blocked. Les règles déterministes restent la référence pour l'autorisation d'une action lorsqu'elles s'appliquent ; la vérification IA constitue une couche supplémentaire et ne doit pas être présentée comme une garantie autonome.

{
  "decision": "approved",
  "reason": "Action passed deterministic controls.",
  "policy_triggered": null,
  "risk_score": 18,
  "risk_breakdown": {"financial": 20,"security": 10},
  "factors": ["transfer"],
  "security": {
    "verdict": "SAFE",
    "analysis": "..."
  }
}

Lorsqu'une règle déterministe bloque l'action, la vérification supplémentaire n'est pas exécutée et la réponse l'indique.

Clés API

Les clés API sont gérées depuis le compte Conforva authentifié et sont liées à son organisation.

GET/v1/api-keys

POST/v1/api-keys

DELETE/v1/api-keys/:id

Ces endpoints de gestion utilisent la session Conforva authentifiée, pas la clé API client. Une nouvelle clé est affichée une seule fois : stockez-la immédiatement.

Utilisation

L'utilisation de l'API est suivie par organisation. Chaque forfait inclut une enveloppe mensuelle d'utilisation API. Lorsque cette enveloppe est épuisée, l'évaluation API s'arrête jusqu'à la prochaine période de facturation.

GET/v1/usage

Erreurs

Statut	Erreur	Signification
400	agent_id_and_action_type_required	Un champ obligatoire est absent.
401	invalid_api_key	La clé Bearer est absente, invalide ou révoquée.
404	agent_not_found	L'agent n'existe pas dans l'organisation de la clé.
503	database_unavailable	Conforva ne peut pas accéder à sa base de données.

Les autres erreurs de validation ou d'exécution sont renvoyées en JSON avec un champ error.

Vérification et autorisation

Conforva sépare les contrôles déterministes des vérifications fondées sur des modèles. Les règles déterministes configurées constituent la frontière d'autorisation lorsqu'elles s'appliquent. La vérification fondée sur un modèle est une couche complémentaire destinée à apporter du contexte et à détecter certains risques.

Pour le flux de réponse des agents, Conforva peut également comparer la demande originale avec une reformulation produite par le modèle principal. Une vérification indépendante répond alors par YES ou NO sur la fidélité de cette reformulation. Un résultat NO signifie que la compréhension n'est pas suffisamment fiable pour poursuivre ce flux.

Les noms et versions des modèles utilisés par l'infrastructure ne sont pas exposés dans cette documentation publique.