DOCUMENTATION API · v1

Connecter une IA à LA CLÉ

Avant d’exécuter une action sensible, votre agent envoie sa demande à LA CLÉ. Le serveur répond immédiatement « autorisé », « refusé » ou « en attente de l’humain ».

Une IA externe doit appeler cette API pour être contrôlée. LA CLÉ ne peut pas intercepter une action provenant d’un outil qui n’a pas intégré ce contrôle.

Démarrage rapide

1Créez un mandat dans votre espace LA CLÉ.
2Copiez le jeton secret affiché une seule fois et stockez-le dans le gestionnaire de 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://la-cle.app/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"],
    "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	Liste des données nécessaires. Chaque élément doit être autorisé par le mandat.
`context`	Non	Métadonnées simples utiles à votre 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. Réutiliser cet identifiant 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"
}

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 demande dans son espace et choisit Autoriser ou Refuser.

curl https://la-cle.app/api/v1/authorizations/AUTHORIZATION_ID \
  -H "Authorization: Bearer lc_live_VOTRE_JETON"

Interrogez cet endpoint à intervalle raisonnable jusqu’à obtenir approved ou blocked. La limite actuelle 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_explicitly_blocked

Action placée dans les interdictions.

action_not_allowed

Action absente de la liste autorisée.

data_scope_not_allowed

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

payment_not_allowed

Le mandat interdit tout paiement.

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 un request_id dérivé de votre opération métier et conservez-le lors des reprises.
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 LA CLÉ.