Pour pseudonymiser des documents via une API en France, la configuration minimale viable repose sur trois éléments : un service qui sépare les domaines de pseudonymisation par application, un transport chiffré (TLS 1.2+) avec authentification forte, et une documentation explicite du mapping et de la réversibilité conforme à l'article 4(5) du RGPD. Choisissez le mode stateless si vous n'avez pas besoin de réidentification ultérieure ; optez pour le mode stateful uniquement si votre cas d'usage l'exige, avec un mapping chiffré et un accès journalisé.
Les références incontournables pour cette mise en œuvre sont la recommandation technique de la CNIL sur le partage sécurisé de données via API, le dépôt open-source Cour-de-cassation/pseudonymisation-api, la documentation produit Teavaro, et la solution SaaS française Safe-doc.
- Vérifiez que vos endpoints exposent au minimum `/pseudonymise` et `/ner`.
- Activez TLS sur tous les appels, sans exception.
- Définissez un domaine distinct par application ou partenaire.
- Décidez du mode stateless ou stateful avant de coder le pipeline.
Conseil de pro : Si vous avez besoin d'analyses croisées sans réidentification, préférez une pseudonymisation déterministe avec un domaine séparé par partenaire. Un HMAC-SHA256 ou une construction FPE (Format-Preserving Encryption) vous permet de rejoindre des jeux de données sans jamais exposer l'identifiant clair.
Points clés
| Point | Détails |
|---|---|
| Séparation des domaines | Un domaine distinct par application empêche le recoupement de bases entre partenaires. |
| Choix d'architecture | Stateless si pas de réidentification ; stateful avec mapping chiffré AES-256-GCM si nécessaire. |
| Checklist CNIL | Documenter les transformations, séparer les bases, vérifier la robustesse contre la réidentification. |
| Authentification | OAuth 2.0 ou mTLS en production, tokens à courte durée de vie pour les LLM externes. |
| Safe-doc | API REST stateless, détection 90+ types PII, export d'audit PDF, zéro stockage de documents. |
Table des matières
- Quels endpoints, paramètres et formats de réponse attendre d'une API de pseudonymisation ?
- Comment pseudonymiser un document via une API, étape par étape
- Authentification, sécurité et choix d'architecture : stateless ou stateful ?
- Checklist CNIL et RGPD pour l'usage d'une API de pseudonymisation en France
- Exemples d'intégration et tests : curl, JavaScript et Python
- Bonnes pratiques et erreurs fréquentes à éviter en production
- Checklist technique et d'audit avant mise en production
- Ce que les guides habituels ne vous disent pas sur la pseudonymisation par API
- Safe-doc : pseudonymisation temps réel, sans stockage, conforme RGPD
- Sources
Quels endpoints, paramètres et formats de réponse attendre d'une API de pseudonymisation ?
Les API de pseudonymisation de documents exposent généralement un ensemble d'endpoints standardisés, dont la connaissance vous évite de redécouvrir la roue à chaque intégration.
Endpoints courants
| Endpoint | Méthode | Rôle |
|---|---|---|
| `/pseudonymise` | POST | Remplace les PII détectées par des pseudonymes (UUID, token, valeur FPE) |
| `/ner` | POST | Détection d'entités nommées ; retourne JSON avec labels et positions |
| `/keys` | GET | Liste les clés de pseudonymisation disponibles par domaine |
| `/variants` | GET | Retourne les variantes de pseudonymisation configurées |
| `/fhir/$de-identify` | POST | Dé-identification de ressources FHIR (santé) |
| `/fhir/$de-pseudonymize` | POST | Réidentification contrôlée de ressources FHIR |
Le dépôt Cour-de-cassation/pseudonymisation-api illustre concrètement l'endpoint `/ner` : il reçoit un objet `Decision { idDocument, text }` et retourne un JSON listant les entités détectées avec leurs positions, accompagné d'une checklist de vérification humaine pour les cas ambigus. La documentation Teavaro montre quant à elle un endpoint `/pseudonymise` qui retourne directement la valeur pseudonymisée, par exemple `{ "pemail": "550e8400-e29b-41d4-a716-446655440000" }`, prête à substituer le PII original.
Paramètres essentiels à documenter
- `resource` / `payload` : le document ou la chaîne à pseudonymiser.
- `domain` : identifiant du domaine de pseudonymisation (clé de séparation par partenaire).
- `key_name` : nom de la clé cryptographique à utiliser.
- `variant` : variante de pseudonymisation (déterministe, aléatoire, FPE).
- `settings` : options complémentaires, par exemple `domain-prefix` pour préfixer les pseudonymes.
- Headers d'authentification : `Authorization: Bearer <token>` ou `X-API-Key: <clé>`.
Codes HTTP et gestion d'erreurs
Les statuts courants sont `200 OK` (traitement synchrone réussi), `202 Accepted` (traitement asynchrone en file), `400 Bad Request` (payload malformé ou format non supporté), `401 Unauthorized` (token absent ou expiré), `403 Forbidden` (domaine non autorisé) et `500 Internal Server Error` (échec du moteur NER ou cryptographique). Pour les fichiers volumineux, privilégiez un mode streaming ou une pagination par blocs de pages plutôt qu'un upload monolithique.
La séparation par domaine n'est pas qu'un paramètre technique : c'est une exigence de gouvernance. Deux partenaires utilisant le même domaine génèrent le même pseudonyme pour un même individu, ce qui crée un risque de recoupement de bases. La recommandation CNIL insiste explicitement sur cette séparation pour prévenir la réidentification indirecte.
Comment pseudonymiser un document via une API, étape par étape
Le pipeline complet suit sept étapes séquentielles. Voici comment les enchaîner en production.
1. Préparer le document. Vérifiez le format (PDF, DOCX, XLSX, CSV, TXT) et l'encodage (UTF-8 recommandé). La taille maximale acceptée varie selon les services ; comptez généralement 10-50 Mo par fichier.
2. Uploader le document. Envoyez le fichier via un POST multipart ou en base64 selon la spécification de l'API.
```bash
curl -X POST https://api.example.com/upload \
-H "Authorization: Bearer $TOKEN" \
-F "file=@contrat.pdf" \
-F "domain=juridique-client-a"
```
3. Déclencher l'extraction OCR si nécessaire. Pour les PDF scannés, l'API lance une étape OCR avant la détection NER. Certains services l'intègrent automatiquement ; d'autres exposent un endpoint `/ocr` séparé.
4. Lancer la détection NER et les règles métier. L'API identifie les entités (noms, SIREN, IBAN, adresses, dates) via un modèle NER et des règles configurables. Le projet enki-run/shield combine spaCy et Presidio avec des règles personnalisables, tout en conservant les en-têtes de colonnes CSV/XLSX intacts.
5. Générer les pseudonymes. Selon la configuration, la valeur de remplacement est un UUID aléatoire, un token HMAC déterministe, ou une valeur FPE conforme au RFC 5297 qui préserve le format original (utile pour les numéros de téléphone ou les codes postaux).
6. Récupérer le document pseudonymisé et le mapping. L'API retourne le document traité et, si le mode stateful est activé, un mapping chiffré `{ pseudonyme: valeur_originale }` à conserver de votre côté.
```bash
curl -X POST https://api.example.com/pseudonymise \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"document_id": "doc-123", "domain": "juridique-client-a", "variant": "deterministic"}'
```
7. Journaliser et exporter le mapping. Enregistrez l'identifiant de traitement, l'horodatage, le domaine et le hash du document original. Exportez le mapping chiffré dans un coffre séparé de la base de production.
Formats supportés et limites techniques
- PDF (natif et scanné avec OCR), DOCX, XLSX, CSV, TXT sont les formats les plus répandus.
- Les fichiers XLSX et CSV : les en-têtes de colonnes ne doivent jamais être pseudonymisés.
- Limite d'encodage : UTF-8 obligatoire pour les fichiers texte ; les encodages legacy (ISO-8859-1) doivent être convertis en amont.
Conseil de pro : Conservez toujours les en-têtes de colonnes CSV/XLSX inchangés. Pseudonymiser les noms de colonnes casse la compatibilité de tous vos pipelines avals, des requêtes SQL aux imports BI. Traitez uniquement les valeurs de cellule.
Authentification, sécurité et choix d'architecture : stateless ou stateful ?
Le choix entre stateless et stateful conditionne à la fois votre posture RGPD et votre surface d'attaque.
Stateless vs stateful : les implications concrètes
En mode stateless, l'API ne conserve aucun mapping après le traitement. Le document pseudonymisé est retourné immédiatement, sans persistance côté serveur. La réidentification devient impossible sans que le client ne conserve lui-même le mapping. C'est l'architecture recommandée pour les traitements LLM externes et les cas où la réidentification n'est jamais nécessaire.
La réidentification reste possible via une procédure contrôlée, journalisée et à accès restreint. Le cookbook eHealth décrit une méthode avancée basée sur ECC et aveuglement (blinding) : ni le client ni le service central ne peuvent seuls reconstruire l'identifiant clair sans procédure conjointe.
| Critère | Stateless | Stateful |
|---|---|---|
| Stockage du mapping | Aucun côté serveur | Persisté (chiffré) |
| Réidentification | Impossible sans mapping client | Possible via procédure contrôlée |
| Cas d'usage recommandé | LLM externes, analyses sans retour | Dossiers médicaux, juridique avec archivage |
| Risque principal | Perte définitive si mapping client perdu | Fuite du mapping = réidentification |
| Conformité RGPD | Simplifiée (pas de base de mapping) | Exige DPA, accès restreint, journalisation |
Options d'authentification
- Clé API (`X-API-Key`) : simple à implémenter, suffisant pour des environnements internes contrôlés.
- OAuth 2.0 (client credentials) : recommandé pour les intégrations machine-to-machine en production.
- mTLS : authentification mutuelle par certificat, pour les environnements à haute exigence de sécurité.
Quelle que soit l'option choisie, implémentez une rotation régulière des clés et stockez-les dans un coffre à secrets (HashiCorp Vault, AWS Secrets Manager ou équivalent). Les tokens d'accès doivent avoir une durée de vie courte, surtout pour les traitements impliquant des LLM externes.
Mesures complémentaires obligatoires
- TLS 1.2 minimum sur tous les endpoints, avec HSTS activé.
- Chiffrement au repos des mappings en AES-256-GCM (comme le fait enki-run/shield).
- Journalisation d'accès immuable : qui a accédé à quel domaine, quand, avec quel résultat.
- Séparation des environnements : ne jamais utiliser des clés de production en développement.
Conseil de pro : Pour les traitements via LLM externes (ChatGPT, Claude), n'accordez que des tokens à courte durée de vie (15-30 minutes maximum) et limitez leur périmètre au seul domaine concerné. Un token compromis ne doit jamais donner accès à l'ensemble des domaines de pseudonymisation.
Checklist CNIL et RGPD pour l'usage d'une API de pseudonymisation en France
La recommandation technique de la CNIL sur le partage sécurisé de données via API pose des exigences précises que tout déploiement en France doit respecter.
Points obligatoires
- Documenter les transformations appliquées : algorithme, domaine, version du modèle NER, date de mise à jour des règles.
- Séparer physiquement ou logiquement la base source des données brutes de la base des pseudonymes.
- Vérifier la robustesse du procédé face aux méthodes de réidentification connues (attaques par recoupement, inférence, singling-out).
- Définir une politique de conservation minimale : ne conserver les mappings que le temps strictement nécessaire.
Points fortement recommandés
- Fournir aux réutilisateurs une documentation décrivant la fréquence de mise à jour, la granularité des données, les formats, la profondeur historique et les mesures de pseudonymisation appliquées.
- Mettre en place un export des journaux d'audit au format PDF ou structuré, consultable par le DPO.
- Définir une politique de réversibilité explicite : qui peut demander la réidentification, dans quel délai, avec quelle traçabilité.
- Restreindre l'accès aux clés de déchiffrement et journaliser chaque utilisation.
La pseudonymisation selon l'article 4(5) du RGPD ne dispense pas du respect des principes de minimisation et de limitation de la conservation. Elle réduit le risque résiduel, mais les données pseudonymisées restent des données à caractère personnel tant que le mapping existe. La recommandation CNIL rappelle que la séparation des bases est la mesure organisationnelle la plus efficace pour limiter ce risque.
Les guides Etalab sur la pseudonymisation complètent ce cadre avec des bonnes pratiques françaises pour la gouvernance des données partagées, notamment sur la documentation des méthodes et la traçabilité des transformations.
Pour les équipes qui gèrent des documents sensibles au sens de l'article 4(5) du RGPD, la page pseudonymisation RGPD de Safe-doc détaille les distinctions légales entre anonymisation et pseudonymisation et leurs implications pratiques pour la documentation.
Exemples d'intégration et tests : curl, JavaScript et Python
Snippets prêts à l'emploi
curl
```bash
Pseudonymisation d'un document texte
curl -X POST https://api.example.com/pseudonymise \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"text": "Jean Dupont, IBAN FR76 3000 6000 0112 3456 7890 189",
"domain": "comptabilite-client-b",
"variant": "deterministic"
}'
Réponse attendue :
{ "pseudonymised_text": "PERS_001, IBAN XXXX_001", "mapping_id": "map-abc123" }
```
JavaScript (fetch)
```javascript
const response = await fetch('https://api.example.com/pseudonymise', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
text: documentContent,
domain: 'juridique-client-a',
variant: 'deterministic'
})
});
const data = await response.json();
console.log(data.pseudonymised_text);
```
Python (requests)
```python
import requests
response = requests.post(
'https://api.example.com/pseudonymise',
headers={'Authorization': f'Bearer {token}'},
json={
'text': document_content,
'domain': 'rh-interne',
'variant': 'random'
}
)
result = response.json()
print(result['pseudonymised_text'])
```
Stratégie de tests automatisés
1. Tests de non-translation des en-têtes : vérifiez que les noms de colonnes CSV/XLSX sont identiques avant et après traitement.
2. Tests de réversibilité (si activée) : pseudonymisez une valeur, réidentifiez-la, comparez avec l'original.
3. Assertion sur le mapping chiffré : vérifiez que le mapping retourné est bien chiffré (non lisible en clair).
4. Tests de charge basiques : envoyez 50 requêtes concurrentes et mesurez la latence moyenne et le taux d'erreur.
5. Tests de régression NER : maintenez un jeu de fixtures avec des entités connues et vérifiez que le taux de détection ne régresse pas entre versions.
Conseil de pro : Dans votre pipeline CI/CD, utilisez exclusivement des fixtures anonymisées (jamais de données de production réelles) et simulez des domaines séparés pour chaque environnement de test. Un test qui passe en production avec de vraies données PII est une violation RGPD potentielle, même en contexte de test.
Checklist avant mise en production
- Format du document vérifié et encodage UTF-8 confirmé.
- Gestion des erreurs HTTP 400/401/403/500 implémentée côté client.
- Quotas et rate-limiting documentés et testés.
- SLA de l'API vérifié et alertes de latence configurées.
Bonnes pratiques et erreurs fréquentes à éviter en production
Bonnes pratiques
- Attribuez un domaine distinct par application, par partenaire et par environnement (dev/staging/prod).
- Activez une journalisation immuable : chaque appel doit tracer l'identifiant de requête, le domaine, l'horodatage et le résultat.
- Chiffrez systématiquement les mappings au repos en AES-256-GCM.
- Minimisez les données envoyées à l'API : n'envoyez que les champs nécessaires, pas le document entier si seule une section contient des PII.
- Révisez régulièrement les règles NER et les patterns de détection, au moins à chaque mise à jour du modèle de langage sous-jacent.
Erreurs courantes
- Pseudonymiser les en-têtes de fichier : casse tous les pipelines avals qui s'appuient sur les noms de colonnes.
- Oublier la séparation de domaine : deux applications partageant le même domaine peuvent recouper leurs bases de pseudonymes.
- Stocker les mappings sans chiffrement : un mapping en clair est une base de réidentification directe.
- Utiliser des tokens à longue durée de vie pour les LLM externes : le Shadow AI se nourrit précisément de ce type d'accès non contrôlé.
- Ne pas tester la gestion des erreurs : une API qui retourne 500 sans que le client ne le gère peut silencieusement laisser passer des PII non pseudonymisés.
La séparation des domaines réduit directement le risque de recoupement de bases, un point que la recommandation CNIL identifie comme la mesure organisationnelle prioritaire pour limiter la réidentification indirecte.
Indicateurs opérationnels à surveiller
- Taux d'erreurs NER (entités manquées ou faux positifs).
- Volume de requêtes par seconde et latence moyenne par endpoint.
- Nombre d'incidents de confidentialité déclarés (accès non autorisé au mapping, token compromis).
Conseil de pro : Documentez les décisions de design dans votre dépôt (pourquoi stateless plutôt que stateful, pourquoi ce domaine, pourquoi ce variant). Un audit RGPD demande précisément ces justifications. Un README bien tenu vaut mieux qu'un rapport rédigé après coup sous pression.
Checklist technique et d'audit avant mise en production
Contrôles techniques
1. TLS 1.2+ activé sur tous les endpoints, certificat valide et HSTS configuré.
2. Rotation des clés API planifiée (au moins tous les 90 jours) et procédure documentée.
3. Rate-limiting et quotas configurés pour prévenir les abus et les surcharges.
4. Sauvegarde des mappings chiffrés dans un coffre séparé de la base de production.
5. Purge automatique des mappings selon la politique de conservation définie.
Contrôles RGPD et gouvernance
- Documentation pour les réutilisateurs rédigée et validée par le DPO.
- DPA (accord de traitement des données) signé avec le fournisseur de l'API.
- Règles de conservation des mappings définies et implémentées.
- Procédure de réidentification temporaire documentée, journalisée et à accès restreint.
Tests requis avant ouverture
- Tests d'intégration couvrant les formats PDF, DOCX, CSV et les cas d'erreur.
- Tests de charge validant la tenue sous le volume de production attendu.
- Revue de sécurité (pentest ou revue de code) sur les endpoints exposés.
- Audit des journaux : vérifier que chaque appel est tracé et que les logs sont immuables.
- Génération d'un rapport PDF d'auditabilité et vérification de sa complétude.
Opérations
- Plan de rollback documenté en cas de défaillance de l'API.
- SLA de l'API vérifié et alertes de disponibilité configurées.
- Monitoring des endpoints principaux avec seuils d'alerte sur la latence et le taux d'erreur.
- Procédure d'escalade en cas d'incident de confidentialité.
Ce que les guides habituels ne vous disent pas sur la pseudonymisation par API
La plupart des articles sur la pseudonymisation par API s'arrêtent à la liste des endpoints et à un snippet curl. C'est insuffisant pour un déploiement sérieux.
Le vrai risque n'est pas technique : c'est organisationnel. Des équipes qui implémentent correctement TLS et OAuth 2.0, mais qui partagent un seul domaine de pseudonymisation entre cinq applications, créent un graphe de recoupement que n'importe quel analyste peut exploiter. La séparation des domaines est la mesure la plus sous-estimée de toute l'architecture.
L'autre angle mort concerne le Shadow AI. Quand un collaborateur copie-colle un contrat dans ChatGPT sans passer par une couche de pseudonymisation, ce n'est pas un problème de sécurité réseau : c'est un problème de gouvernance que l'API seule ne résout pas. L'API doit être couplée à une politique d'accès et à des tokens à courte durée de vie pour que la protection soit réelle.
Enfin, le mode stateless est souvent présenté comme « plus simple ». Il l'est techniquement, mais il transfère la responsabilité du mapping vers le client. Si ce mapping est perdu, la réidentification devient définitivement impossible, ce qui peut poser des problèmes légaux dans des contextes où la réidentification est une obligation (dossiers médicaux, procédures judiciaires). Choisissez votre architecture en connaissance de cause, pas par défaut.
Safe-doc : pseudonymisation temps réel, sans stockage, conforme RGPD
Mettre en place une API de pseudonymisation de documents conforme au RGPD demande du temps : choix d'architecture, gestion des clés, documentation pour le DPO, tests de charge. Safe-doc compresse ce délai en proposant une API REST prête à l'emploi, en mode stateless par défaut, avec détection automatique de plus de 90 types de PII sur PDF, DOCX, XLSX et TXT.
Aucun document n'est stocké côté serveur. Le mapping chiffré est exportable pour vos besoins d'audit, et un rapport PDF d'auditabilité est généré à chaque traitement. Pour les équipes qui utilisent des LLM externes (ChatGPT, Claude), Safe-doc s'intègre comme couche de pseudonymisation en amont, ce qui neutralise le risque Shadow AI sans modifier les habitudes de travail. Les détails d'architecture et les garanties de sécurité sont publiquement documentés.
Pour les DPO et responsables IT qui ont besoin d'une traçabilité complète, la page dédiée à la conformité et à l'audit détaille les fonctionnalités d'auditabilité et les options de déploiement. Demandez un accès API ou une démonstration directement depuis cette page.
Sources
- Recommandation technique relative à l'utilisation des interfaces de programmation applicatives (API) pour le partage sécurisé de données à caractère personnel
- Blinded pseudonymisation REST service Cookbook Version 1.9
- Cour-de-cassation/pseudonymisation-api
- Pseudonymisation API | Product & Technical Documentation
Cet article constitue une information générale et ne remplace pas l'avis d'un avocat qualifié. Consultez un professionnel du droit qualifié à propos de votre cas personnel avant d'agir sur la base de ce contenu.