API TokenVeil v1

Référence interactive (en anglais, c’est un contrat développeur) : explorez les endpoints, schémas, codes d’erreur et exemples de code, générés depuis la spécification OpenAPI du produit.

L’API v1 expose l’anonymisation réversible de TokenVeil sous forme de service. Vous envoyez un texte, vous recevez sa version tokenisée et un identifiant de session opaque, vous utilisez le texte tokenisé où vous voulez (votre propre LLM, un pipeline de données, un tiers), puis vous rappelez avec l’identifiant de session pour restaurer les valeurs réelles.

La table de correspondance token vers valeur ne quitte jamais le serveur. Elle est chiffrée au repos et n’est adressable que par l’identifiant de session, un jeton de capacité de 256 bits, non énumérable. TokenVeil n’envoie vos données réelles nulle part : votre infrastructure les garde, l’API ne fait circuler que du texte tokenisé et des identifiants opaques.

URL de base

https://<votre-hote-tokenveil>/api/v1

L’API est servie par votre propre instance TokenVeil. Il n’y a pas de cloud TokenVeil partagé : l’URL de base est l’hôte où vous avez déployé TokenVeil (Community ou Enterprise).

Authentification

Chaque appel exige une clé API dans l’en-tête X-TV-API-Key.

Créez une clé depuis l’interface TokenVeil : Préférences > onglet “Clé API” > Générer une clé API. Une clé porte une expiration optionnelle et un quota journalier, et peut être révoquée à tout moment. Conservez-la comme un mot de passe : elle donne accès à l’anonymisation et à la désanonymisation sur votre compte.

X-TV-API-Key: tkv_xxxxxxxxxxxxxxxxxxxxxxxx

Toutes les sessions sont cloisonnées au compte porteur de la clé. Une clé ne peut lire et désanonymiser que les sessions qu’elle a créées. L’identifiant de session d’un autre compte renvoie 404, même si vous le détenez d’une manière ou d’une autre.

Endpoints

POST /api/v1/anonymize

Anonymise un texte et ouvre une session de mapping.

Corps de la requête :

Champ	Type	Requis	Description
text	string	oui	Texte à anonymiser. 100000 caractères max.
expires_in_hours	integer ou null	non	Durée de vie de la session, 1 à 2160 heures (90 jours). 24 par défaut. null n’expire jamais.
title	string ou null	non	Libellé interne pour retrouver la session. Jamais envoyé à un LLM. 80 caractères max.

curl -X POST https://<hote>/api/v1/anonymize \
  -H "X-TV-API-Key: $TV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Contactez Jean Dupont au 06 12 34 56 78, IBAN FR76 3000 6000 0112 3456 7890 189."}'

Réponse 200 :

{
  "session_id": "TV-9f2c8a1b...",
  "anonymized_text": "Contactez <PERSON_1> au <PHONE_NUMBER_1>, IBAN <IBAN_CODE_1>.",
  "detected": { "PERSON": 1, "PHONE_NUMBER": 1, "IBAN_CODE": 1 },
  "expires_at": 1793894400.0
}

detected ne rapporte que les types d’entités et leur nombre, jamais les valeurs réelles. Conservez session_id : c’est le seul moyen de restaurer les valeurs réelles plus tard.

POST /api/v1/deanonymize

Restaure les valeurs réelles dans un texte tokenisé, à l’aide de son identifiant de session. Vous passez typiquement une réponse de LLM qui porte encore les tokens.

Corps de la requête :

Champ	Type	Requis	Description
session_id	string	oui	L’identifiant renvoyé par /anonymize.
text	string	oui	Texte tokenisé à retraduire. 500000 caractères max. Les tokens absents du mapping sont laissés tels quels.

curl -X POST https://<hote>/api/v1/deanonymize \
  -H "X-TV-API-Key: $TV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "TV-9f2c8a1b...", "text": "J'\''ai appelé <PERSON_1> au <PHONE_NUMBER_1>."}'

Réponse 200 :

{ "text": "J'ai appelé Jean Dupont au 06 12 34 56 78." }

Chaque désanonymisation est auditée (événement de ré-identification) et incrémente le compteur d’usages de la session.

GET /api/v1/sessions/{session_id}

Renvoie le statut d’une session sans jamais déchiffrer le mapping.

Réponse 200 :

{
  "session_id": "TV-9f2c8a1b...",
  "title": null,
  "status": "active",
  "created_at": 1793808000.0,
  "expires_at": 1793894400.0,
  "uses": 3,
  "last_used_at": 1793820000.0
}

status vaut active, expired ou revoked.

DELETE /api/v1/sessions/{session_id}

Détruit le mapping d’une session immédiatement et de façon irréversible. Tout texte tokenisé déjà émis ne pourra plus être retraduit. Renvoie 204 sans corps.

Erreurs

Statut	Signification
401	Clé API absente ou invalide.
403	Licence TokenVeil expirée sur l’instance.
404	Identifiant de session inconnu, ou session appartenant à un autre compte.
410	Session expirée ou révoquée.
422	Corps invalide (par exemple texte au-delà de la limite de taille).
429	Quota journalier de la clé ou rate limit de rafale atteint.

Les corps d’erreur suivent la forme standard {"detail": "..."}.

Modèle de sécurité

• Le mapping est stocké chiffré au repos (AES via Fernet) et n’est atteignable que par l’identifiant de session.
• L’identifiant de session est un jeton de capacité opaque de 256 bits, pas un id de ligne en base : il ne peut être ni deviné ni énuméré.
• Les sessions sont isolées par clé : une clé ne voit ni ne restaure jamais les sessions d’un autre compte.
• L’API publique n’expose jamais le mapping en clair. Il n’existe pas d’endpoint d’export de clé sur /api/v1.
• Les clés expirent, portent un quota journalier, sont rate limitées et révocables. La révocation et l’état de licence sont vérifiés à chaque appel.
• L’anonymisation enregistre le nombre d’entités par type, et la désanonymisation enregistre un événement de ré-identification, les deux sans les valeurs réelles, pour l’audit.

Stabilité

/api/v1 est une surface stable et versionnée. Les changements cassants passent à une nouvelle version (/api/v2) ; v1 continue de fonctionner. Une spec OpenAPI curée et exploitable par machine est servie à /api/v1/openapi.json, et un Swagger UI interactif à /api/v1/docs. Les deux sont limités à la surface publique /api/v1 (les routes internes ne sont pas exposées).