DOCUMENTATION API · v3

Connecter une chaîne d’IA à KYVLT

Avant une action sensible, l’agent envoie l’action, sa chaîne d’acteurs et son niveau de risque. KYVLT applique la règle côté serveur puis renvoie une décision et, lorsqu’elle est finale, un reçu vérifiable.

Une IA externe doit appeler cette API pour être contrôlée. KYVLT ne peut pas intercepter une action provenant d’un outil qui n’a pas intégré ce contrôle. Les passeports sont aujourd’hui auto-déclarés et ne constituent pas une identité légale.

Démarrage rapide

1Enregistrez l’agent et son passeport dans votre espace KYVLT.
2Créez un mandat puis stockez son jeton dans le coffre à secrets de l’agent.
3Avant l’action réelle, appelez POST /api/v1/authorize.
4N’exécutez l’action que si authorized vaut true.

curl -X POST https://kyvlt.com/api/v1/authorize \
  -H "Authorization: Bearer lc_live_VOTRE_JETON" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "réserver",
    "amount_cents": 28600,
    "merchant": "Hôtel Central Lyon",
    "request_id": "reservation_2026_000184",
    "data_scopes": ["Nom et prénom"],
    "actor_chain": ["LCA-7K9P2-M4Q8R", "LCA-2D6NX-8VQ3K"],
    "risk_level": "medium",
    "reversible": true,
    "destination_country": "FR",
    "context": { "city": "Lyon", "refundable": true }
  }'

Champs de la requête

Champ	Obligatoire	Rôle
`action`	Oui	Action exacte à comparer au mandat, par exemple réserver.
`request_id`	Oui	Identifiant unique et stable de l’opération, entre 8 et 120 caractères.
`amount_cents`	Non	Montant entier dans la plus petite unité monétaire. 28600 = 286,00 €.
`merchant`	Non	Commerçant, service ou destinataire concerné.
`data_scopes`	Non	Données nécessaires ; chaque élément doit être autorisé par le mandat.
`actor_chain`	Non	Passeports LCA ordonnés de l’agent racine au dernier sous-agent.
`risk_level`	Non	low, medium, high ou critical. Par défaut : medium.
`reversible`	Non	Indique si l’action peut réellement être annulée.
`destination_country`	Non	Code pays ISO à deux lettres lorsque la politique l’exige.
`context`	Non	Métadonnées simples utiles au journal. Ne placez aucun secret ici.

Idempotence : renvoyer le même request_id et le même contenu retourne la décision existante sans redéduire le budget. Le réutiliser avec un autre contenu renvoie HTTP 409.

Lire la réponse

{
  "authorized": true,
  "status": "approved",
  "reason": "authorized",
  "authorization_id": "auth_…",
  "request_id": "reservation_2026_000184",
  "mandate_code": "CLE-XXXX-XXXX-XXXX",
  "remaining_budget_cents": 11400,
  "expires_at": "2026-09-19T20:00:00.000Z",
  "decided_at": "2026-09-18T14:05:00.000Z",
  "receipt": {
    "code": "RCP-XXXX-XXXX-XXXX",
    "proof_hash": "…",
    "verify_url": "https://kyvlt.com/receipts/RCP-XXXX-XXXX-XXXX"
  }
}

Le reçu final relie trois empreintes : l’action, la politique appliquée et la preuve complète. Sa page publique ne révèle pas le contenu privé de l’action.

HTTP 200

Approuvé

L’action peut être exécutée.

HTTP 202

En attente

Une personne doit décider.

HTTP 403

Refusé

L’action ne doit pas partir.

Lorsqu’un accord humain est requis

Un mandat configuré sur « Confirmer chaque action » retourne HTTP 202 avec reason: human_confirmation_required. Le titulaire voit la chaîne d’agents, le risque, le montant, le service et les données avant de choisir.

curl https://kyvlt.com/api/v1/authorizations/AUTHORIZATION_ID \
  -H "Authorization: Bearer lc_live_VOTRE_JETON"

Interrogez cet endpoint à intervalle raisonnable jusqu’à obtenir approved ou blocked. La limite est de 120 lectures par minute et par jeton.

Principaux motifs de refus

mandate_not_active

Mandat révoqué ou inactif.

mandate_expired

La date limite est dépassée.

action_not_allowed

Action absente de la liste autorisée.

data_scope_not_allowed

Une donnée dépasse le périmètre.

risk_level_exceeded

Le risque dépasse le plafond.

reversible_action_required

Le mandat exige une action réversible.

destination_country_not_allowed

Le pays n’est pas autorisé.

delegation_depth_exceeded

La chaîne d’agents est trop profonde.

unregistered_agent_in_chain

Un agent n’a pas de passeport reconnu.

action_rate_exceeded

La cadence horaire est atteinte.

budget_exceeded

Le budget restant est insuffisant.

human_denied

Le titulaire a refusé la demande.

Bonnes pratiques indispensables

Gardez le jeton côté serveur ou dans un coffre à secrets, jamais dans du JavaScript public.
Utilisez le passeport exact de chaque agent et ne cachez jamais une sous-délégation.
Réutilisez le même request_id lors d’une reprise réseau.
En cas de fuite possible, révoquez le mandat et créez-en un nouveau.
Traitez toute erreur réseau comme un refus provisoire ; ne contournez jamais KYVLT.