Kostenlos testen
API v1 · Stand 27. September 2026

API-Dokumentation Beta

Der Pseudonymisierer bietet drei gleichwertige Wege: eine REST-API, einen Proxy im OpenAI- und Anthropic-Format sowie einen MCP-Server. Alle nutzen dieselben Sitzungen und Zuordnungen. Die vollständige Schema-Beschreibung liefert Swagger bzw. ReDoc, das rohe Schema liegt unter /openapi.json.

Grundprinzip

Sie schicken Text (oder JSON/Tabellen) an den Pseudonymisierer. Er erkennt personenbezogene Daten, ersetzt sie durch konsistente Ersatzwerte und legt die Zuordnung verschlüsselt in einer Sitzung ab. Den pseudonymisierten Text geben Sie an ein Cloud-Modell. Dessen Antwort schicken Sie mit derselben Sitzungs-ID zurück; der Personifizierer setzt die Originale wieder ein – auch bei Beugungen, veränderter Schreibweise oder Platzhalter-Varianten.

Pseudonyme sind deterministisch: dasselbe Original ergibt für Ihr Konto immer dasselbe Pseudonym, auch über Sitzungen hinweg. Mehrstufige Agenten bleiben deshalb konsistent, ohne dass Sie Sitzungs-IDs verwalten müssen.

Erkennungsstufen

Stufe A (jeder Tarif): ein kleines, schnelles KI-Erkennungsmodell (GLiNER) plus spaCy und deutsche Muster für Adressen, IBANs, Kennungen und Anreden – unter einer Sekunde je Seite. Stufe B (Business, On-Premise; Parameter llm: true): zusätzlich liest ein großes Sprachmodell den Text ein zweites Mal und ergänzt seltene Schreibweisen – rund 15–20 Sekunden je Aufruf. Beide Stufen laufen ausschließlich auf dem Server des Pseudonymisierers in Deutschland (oder Ihrer eigenen Installation); an das Cloud-Modell geht in keiner Stufe Klartext. Der Schnellmodus (schnell: true) verzichtet auf beide Modelle und nutzt nur Muster und das Wörterbuch der Sitzung – für Werkzeugergebnisse in Agenten-Schleifen.

Authentifizierung

Jede Anfrage trägt Ihren Schlüssel als Header X-API-Key: psk_live_… oder Authorization: Bearer psk_live_…. Schlüssel erhalten Sie über die Registrierung (Testzugang) oder im Konto; dort lässt er sich jederzeit kopieren und erneuern. Serverseitig liegt der Schlüssel als Hash (Prüfung) und verschlüsselt (erneutes Kopieren im Konto), nie im Klartext.

EndpunktZweck
POST /api/registrierenTestzugang anlegen (Name, E-Mail, datenschutz: true) – liefert den Schlüssel vollständig
GET /api/kontoTarif, Gültigkeit, Nutzung im laufenden Monat, Anzahl Sitzungen, Kurzform des Schlüssels (schluessel_hinweis, z. B. psk_live_Ab3…x9Kz)
GET /api/konto/schluesselEigenen Schlüssel vollständig abrufen (Kopier-Symbol im Konto; Antwort mit Cache-Control: no-store)
POST /api/konto/schluesselNeuen Schlüssel erzeugen (alter sofort ungültig)
POST /api/meldungenFehler melden (siehe Fehler melden)
GET /api/tarifeÖffentliche Tarifübersicht

Aufrufe aus dem Browser (CORS)

Standardmäßig beantwortet der Pseudonymisierer keine Aufrufe aus dem JavaScript fremder Websites – der Browser meldet dann einen CORS-Fehler. Das ist Absicht: Ein API-Schlüssel im Browser-Code einer öffentlichen Website ist für jeden Besucher sichtbar und lässt sich missbrauchen. Empfohlen: Rufen Sie die API aus dem Server Ihrer Website auf (PHP, Node, Python …); dort bleibt der Schlüssel geheim und CORS spielt keine Rolle. Für interne Werkzeuge und geschützte Oberflächen können wir Ihre Ursprünge freigeben (Einstellung PSEUDO_CORS_ORIGINS, z. B. ["https://intranet.firma.de"]) – nennen Sie uns die Adresse; bei eigener Installation tragen Sie sie selbst ein.

Demo-Widget ohne Schlüssel (für beliebig viele Domains)

Für Vorführungen auf Websites – auch auf vielen Domains zugleich – gibt es ein fertiges Widget, das keinen Schlüssel braucht: Es spricht den öffentlichen Demo-Endpunkt POST /api/demo an, der von jeder Domain aus erreichbar ist (CORS für alle Ursprünge, nur für die Demo-Pfade). Der Endpunkt arbeitet ausschließlich mit Stufe A (keine LLM-Stufe, keine Cloud), begrenzt Texte auf 4.000 Zeichen und 30 Aufrufe je Stunde und Besucher; Sitzungen leben 30 Minuten nur im Arbeitsspeicher, Inhalte werden nicht protokolliert. Zwei Zeilen genügen:

<div data-pseudonymisierer-widget></div>
<script src="https://pseudonymisierer.de/static/widget.js" async></script>

Das Widget bringt seine Gestaltung im Shadow DOM mit und stört die Stile der Website nicht. Optionen am Container: data-titel="…" (Überschrift), data-beispiel="…" (eigener Beispieltext), data-link="nein" (Verweis auf pseudonymisierer.de ausblenden). Eigene Oberflächen rufen https://pseudonymisierer.de/api/demo direkt per fetch auf – mit {"schritt":"pseudonymisieren","text":"…"} bzw. {"schritt":"personifizieren","sitzung":"…","text":"…"}, ohne Schlüssel und ohne besondere Header. Für produktive Nutzung mit eigenem Kontingent und Stufe B bleibt der Weg über die Server-Brücke:

Einbindung in die eigene Website (serverseitig)

Empfohlener Weg für Websites: Eine kleine Server-Brücke hält den API-Schlüssel auf Ihrem Webserver; das JavaScript der Seite spricht nur die eigene Website an (gleicher Ursprung, kein CORS, kein Schlüssel im Browser). Die Brücke lässt nur die Aktionen Pseudonymisieren/Personifizieren zu, begrenzt Textlänge und Aufrufe je Besucher und prüft, dass der Aufruf von der eigenen Website kommt.

WebsitePaketEinrichtung
PHP (auch Shared Hosting wie All-Inkl)pseudonymisierer-php-bruecke.zip1. pseudonymisierer-bruecke.php und pseudonymisierer.js ins Web-Verzeichnis laden. 2. pseudonymisierer-konfiguration.beispiel.php nach pseudonymisierer-konfiguration.php kopieren, API-Schlüssel eintragen. 3. Im HTML <script src="/pseudonymisierer.js"></script> und <div data-pseudonymisierer-demo></div> (fertiges Widget) oder eigene Aufrufe über window.Pseudonymisierer. Beispiel: beispiel.html im Paket.
WordPresspseudonymisierer-wordpress.zipPlugin hochladen und aktivieren, unter Einstellungen → Pseudonymisierer den Schlüssel eintragen, Shortcode [pseudonymisierer_demo] einfügen. Eigenes JavaScript nutzt dieselbe Funktion window.Pseudonymisierer; die REST-Route pseudonymisierer/v1/aufruf ist per Nonce auf die eigene Website beschränkt.
Node, Python, andere–Die API direkt vom Server aus aufrufen (siehe REST-Endpunkte); der Schlüssel liegt in der Server-Konfiguration, der Browser bekommt nur das Ergebnis.
// JavaScript der Website – Schlüssel bleibt auf dem Server
const e = await Pseudonymisierer.pseudonymisieren(text);            // { text, sitzung, treffer }
const antwort = await meineKI(e.text);                               // Cloud-Modell sieht nur Pseudonyme
const z = await Pseudonymisierer.personifizieren(antwort, e.sitzung); // { text, ersetzt }

Schnellstart

curl https://pseudonymisierer.de/api/pseudonymisieren \
  -H "X-API-Key: psk_live_…" -H "content-type: application/json" \
  -d '{"text": "Frau Anna Schmidt (anna@schmidt-bau.de) bittet um ein Angebot."}'

{"text": "Frau Marliese Koch (marliese@koch-technik.de) bittet um ein Angebot.",
 "sitzung": "s_acGvuqjpmHd9amul3oyp7g", "anzahl": 2,
 "je_typ": {"PERSON": 1, "EMAIL_ADDRESS": 1}, "warnungen": [], "dauer_ms": 637,
 "treffer": [{"typ": "PERSON", "start": 0, "ende": 17, "pseudonym": "Frau Marliese Koch", "score": 0.95, "quelle": "GLiNERRecognizer"}, …]}

curl https://pseudonymisierer.de/api/personifizieren \
  -H "X-API-Key: psk_live_…" -H "content-type: application/json" \
  -d '{"text": "Angebot an Frau Koch gesendet.", "sitzung": "s_acGvuqjpmHd9amul3oyp7g"}'

{"text": "Angebot an Frau Schmidt gesendet.", "ersetzt": 1, "details": [{"pseudonym": "Koch", "original": "Schmidt", "anzahl": 1, "methode": "exakt"}], "nicht_gefunden": […]}

REST-Endpunkte

Methode & PfadAnfrage (JSON)Antwort
POST /api/pseudonymisierentext (Pflicht), sitzung, modus (realistisch|platzhalter), entitaeten (Liste), erlaubnisliste, sperrliste ("Begriff" oder "Begriff=TYP"), llm (bool), schnell (bool), mit_originalen (bool)text, sitzung, anzahl, je_typ, treffer[] (Typ, Position, Pseudonym, Score, Quelle), warnungen, dauer_ms
POST /api/personifizierentext, sitzung (Pflicht), fuzzy (bool, Standard true)text, ersetzt, details[], nicht_gefunden[], dauer_ms
POST /api/tabelle/pseudonymisierenzeilen (Liste von Objekten), spalten_typen z. B. {"Name":"PERSON","Betrag":"KEEP","Notiz":"TEXT"}, sitzung, moduszeilen, sitzung, je_typ, warnungen
POST /api/tabelle/personifizierenzeilen, sitzung, fuzzyzeilen, ersetzt
POST /api/struktur/pseudonymisierendaten (beliebiges JSON), sitzung, modus – alle Zeichenketten werden geprüft, Zahlen und Schlüssel bleibendaten, sitzung, warnungen
POST /api/struktur/personifizierendaten, sitzung, fuzzydaten, ersetzt
POST /api/bild/schwaerzenbild (Base64: PNG, JPEG oder WebP; Pflicht), sitzung, elemente (Rechteck und Text aus dem Baum der Bedienelemente), darstellung (ersetzen|schwarz)bild (PNG mit Nachweis), bereiche[], je_typ, nachweis, sitzung – siehe Bildschwärzung
GET /api/sitzungen–Liste Ihrer Sitzungen mit Statistik (ohne Originale)
GET /api/sitzungen/{id}Query mit_originalen=true liefert die ZuordnungStatistik bzw. Zuordnungstabelle
DELETE /api/sitzungen/{id}–{"geloescht": true}
POST /api/sitzungen/kennungtext (Pflicht, höchstens 1.000 Zeichen){"sitzung": "s_…"} – Sitzungskennung aus beliebigem Text, siehe Sitzungen
GET /gesund–Status, Version, geladene Modelle (ohne Schlüssel)

Spaltentypen für Tabellen: TEXT (Freitext mit Erkennung, Standard), KEEP (unverändert), PERSON, ORGANIZATION, ADDRESS, LOCATION, EMAIL_ADDRESS, PHONE_NUMBER, IBAN_CODE, DATE_OF_BIRTH, ID_NUMBER. Typisierte Spalten werden ohne Erkennung direkt ersetzt – schneller und treffsicherer.

Bildschwärzung (Bildschirmfotos)

POST /api/bild/schwaerzen macht personenbezogene Angaben in einem Bildschirmfoto unkenntlich, damit ein Modell mit dem Bild arbeiten kann. Die Texterkennung (RapidOCR mit den PP-OCRv6-Modellen) liest das Bild, die Erkennung des Pseudonymisierers prüft den Text mit der Sitzung der Anfrage – dieselben Angaben bekommen im Bild dieselben Ersatzdaten wie im Text. Schickt der Client die Elemente des Baums der Bedienelemente mit (elemente: Rechteck im Bild und Text), werden deren Bereiche mit denen der Texterkennung vereinigt.

  • Darstellung: Mit ersetzen (Standard) stehen im Bild die Ersatzdaten der Sitzung, wo die Erkennung ganze Wörter ersetzt; alles andere wird deckend schwarz. schwarz schwärzt alles. Das Bild trägt keine sichtbare Kennzeichnung; welche Bereiche ersetzt oder geschwärzt sind, nennt bereiche (Rechteck, Text mit Ersatzdaten bzw. leer, Typ, Herkunft ocr, baum, regel, foto, code).
  • Sicher im Zweifel: Deckend geschwärzt werden auch Werte neben Beschriftungen wie „Telefon“ oder „IBAN“, Tabellenspalten unter solchen Köpfen, Wörter mit „@“ und lange Ziffernfolgen, alles, was die Texterkennung findet, aber nicht sicher liest, sehr kleine Schrift, Fotos und Profilbilder sowie QR- und Strichcodes. Scheitert die Verarbeitung, gibt es kein Bild.
  • Restrisiko: An erfundenen Bildschirmfotos blieben 0,4–1,4 % der bekannten Angaben für eine zweite Texterkennung lesbar (Messung in docs/recherche-bildschwaerzung.md im Repository). Ein Cloud-Modell liest mehr als eine Texterkennung – Bildschirmfotos deshalb nur einschalten, wo der Baum der Bedienelemente nicht reicht.
  • Nachweis: Das PNG trägt einen Nachweis (HMAC über die Bildpunkte, Sitzung und Konto), der selbst keine Kennung nennt; geprüft wird gegen die Sitzung der Anfrage, und der Proxy entfernt ihn, bevor er das Bild an den Anbieter weiterreicht. Der Proxy lässt mit der Medien-Regel nachweis nur solche Bilder zum Modell; ein verändertes Bild oder eine fremde Sitzung verliert ihn.
  • Datenschutz: Das Bild wird nur im Arbeitsspeicher verarbeitet, weder gespeichert noch protokolliert. Der erkannte Text geht wie jeder Text durch die Sitzung.
  • Abrechnung und Grenzen: je Bild (nicht nach Zeichen), höchstens 12 Bilder je Minute und Konto (PSEUDO_BILD_TAKT_MINUTE), Bilder bis 20 MB und 16 Mio. Bildpunkte. Rund 2 s je Bild 1920 × 1080; unter Last übernimmt das kleinere Modell PP-OCRv6 tiny. Fehler: 413 (zu groß), 422 (kein lesbares Bild), 429 (Obergrenze je Minute).

LLM-Proxy (OpenAI- und Anthropic-Format)

Der Proxy pseudonymisiert alle Nachrichten einer Anfrage, leitet sie an den Anbieter weiter und personifiziert die Antwort – Text ebenso wie Argumente von Werkzeugaufrufen (Function Calling / tool_use). Ihre Anwendung braucht dafür keine Änderung außer der Basis-URL.

FormatBasis-URLWeitergeleitete Pfade
OpenAI Chat Completionshttps://pseudonymisierer.de/v1POST /v1/chat/completions, GET /v1/models
Anthropic Messageshttps://pseudonymisierer.dePOST /v1/messages, POST /v1/messages/count_tokens, GET /v1/models, GET /v1/models/{id}

POST /v1/messages/count_tokens durchläuft dieselbe Übersetzung wie die eigentliche Anfrage: Der Anbieter zählt, was er später auch erhält, und sieht dabei nur Pseudonyme. Fehler auf den Proxy-Pfaden kommen zusätzlich im Format der Anbieter ({"type":"error","error":{"type":"…","message":"…"}} neben detail), damit SDKs und Desktop-Anwendungen die Meldung anzeigen.

Header

HeaderBedeutung
Authorization: Bearer psk_… oder x-api-keyIhr Pseudonymisierer-Schlüssel (so, wie das SDK den api_key setzt)
X-Pseudo-Cloud-KeyIhr Schlüssel beim Cloud-Anbieter (OpenAI, Anthropic …). Pflicht – der Pseudonymisierer stellt keine Modellkontingente bereit und speichert diesen Schlüssel nicht. Fehlt er: 402. Ausnahme: Konten im Tarif intern (siehe Konto & Betreiber) nutzen ohne diesen Header den serverseitigen Schlüssel des Betreibers – nur beim eingestellten Anbieter (X-Pseudo-Ziel dann 400) und bis zu ihrer Token-Grenze; schicken sie den Header mit, gilt ihr Schlüssel.
X-Pseudo-ZielAnderer Upstream, z. B. https://openrouter.ai/api oder ein Azure-Endpunkt (Standard: api.openai.com / api.anthropic.com)
X-Pseudo-SitzungSitzung ausdrücklich wiederverwenden (z. B. je Unterhaltung oder Agentenaufgabe); sonst pro Anfrage eine neue, Konsistenz über deterministische Pseudonyme. Die verwendete Sitzung steht in der Antwort im gleichnamigen Header.
X-Pseudo-Modusauto (Standard): System-Prompt und Nutzertext voll analysieren, Werkzeugergebnisse und Modellantworten im Schnellmodus. voll: überall volle Erkennung. schnell: überall nur Muster und Wörterbuch.
X-Pseudo-Erlaubnis, X-Pseudo-SperreKlartext-Regeln je Anfrage: Begriffe, die nie bzw. immer ersetzt werden – URL-kodiert und kommagetrennt, z. B. Muster%20GmbH,DIN%204108; Sperre auch als Begriff%3DTYP. Höchstens 2.000 Zeichen und 50 Einträge je Header, sonst 400 – größere Listen gehören in die Kontoeinstellungen, die Header ergänzen sie.
X-Pseudo-Themen, X-Pseudo-Firmen, X-Pseudo-OrteThemenfelder (marken,produkte,software,normen,medizin), Firmen-Schalter (aus, juristisch, alle) und Orte (ja/nein) je Anfrage; Schalter überschreiben die Kontoeinstellung.
X-Pseudo-Websucheeigen (Suche und Abruf auf dem Pseudonymisierer-Server, Standard) oder anthropic (Server-Werkzeuge des Anbieters) für web_search/web_fetch je Anfrage; überschreibt die Kontoeinstellung. Antwort-Header X-Pseudo-Websuche zeigt den geltenden Modus (siehe Websuche).
X-Pseudo-MedienBilder, PDF- und Audio-Blöcke je Anfrage: durchlassen, schwaerzen, nachweis, entfernen oder abweisen (siehe Medien-Regel). Der Header kann die Einstellung von Konto und Server nur verschärfen. Als Antwort-Header zeigt X-Pseudo-Medien, was geschah, z. B. entfernt=2;text=1.
X-Pseudo-BrueckenNamensmuster von Werkzeugen, die selbst über den Pseudonymisierer arbeiten, kommagetrennt mit * und ? als Platzhaltern, z. B. mcp__browser__* (siehe Brücken-Werkzeuge). Höchstens 50 Muster.
X-Pseudo-Warnung (Antwort)Hinweise, z. B. wenn die LLM-Stufe nicht erreichbar war – ohne Umlaute und Sonderzeichen (ASCII), damit jeder Client die Kopfzeile lesen kann
X-Pseudo-Replay (Antwort)Treffer/Abfragen des Wiedergabe-Speichers für diese Anfrage, z. B. 7/8: sieben von acht Blöcken des Verlaufs kamen unverändert aus der Vorrunde (siehe Replay)
X-Pseudo-Streng1: strenge Restprüfung – der Proxy prüft jede ausgehende Fassung (System-Prompt, Verlauf, Werkzeugergebnisse, auch die der Brücken-Werkzeuge, jede Runde der eigenen Websuche), bevor er das Modell anfragt. Steht noch ein Begriff der Sperrliste oder ein bekanntes Original im Klartext, geht nichts an den Anbieter; Antwort 422 mit error.code restpruefung_fehlgeschlagen. Blöcke, die sich nicht prüfen lassen (Bild ohne Nachweis, Audio, Datei, PDF), gehen auch mit der Medien-Regel durchlassen nicht hinaus: 422 mit medien_nicht_pruefbar. Werkzeugdefinitionen (tools) werden nicht geprüft. Antwort-Header X-Pseudo-Restpruefung: bestanden bzw. fehlgeschlagen. Ohne den Header ändert sich nichts.
X-Pseudo-Klartext (Antwort)Wie viele erkannte Treffer wegen Erlaubnisliste, Themenfeld oder Firmen-Schalter im Klartext blieben, z. B. erlaubnis=2;firmen=1 (siehe Klartext-Regeln)
# Python, OpenAI-SDK
from openai import OpenAI
client = OpenAI(base_url="https://pseudonymisierer.de/v1", api_key="psk_live_…",
                default_headers={"X-Pseudo-Cloud-Key": "sk-…", "X-Pseudo-Sitzung": "auftrag-4711"})
r = client.chat.completions.create(model="gpt-5", messages=[{"role": "user", "content": mail_text}], tools=werkzeuge)

# Node, Anthropic-SDK
const client = new Anthropic({ baseURL: "https://pseudonymisierer.de", apiKey: "psk_live_…",
  defaultHeaders: { "X-Pseudo-Cloud-Key": "sk-ant-…" } });

Streaming

Mit stream: true reicht der Proxy die Server-Sent-Events des Anbieters live durch: Chat-Oberflächen tippen mit, Werkzeugaufrufe kommen an, sobald das Modell sie ausgibt, und lange Antworten laufen nicht in Leerlauf-Timeouts. Dabei gilt:

  • Text läuft durch ein Gleitfenster. Der Proxy hält so viele Zeichen zurück, wie das längste Pseudonym der Sitzung lang ist, schneidet nur an Leerraum und nie mitten in einem erkannten Pseudonym. Freigegebener Text wird sofort personifiziert gesendet.
  • Werkzeug-Eingaben (tool_use bzw. tool_calls) werden je Aufruf bis zum Ende gesammelt, als Ganzes personifiziert und vor dem Abschluss als ein Stück gesendet. Ihre Anwendung führt das Werkzeug also mit echten Daten aus. Im OpenAI-Format geht der erste Chunk mit id und name sofort hinaus, die Argumente folgen vollständig.
  • Denk-Blöcke (thinking, signature) und alle übrigen Ereignisse (ping, usage, Zitate, Fehler) passieren unverändert; die Signatur bleibt gültig.
  • Lebenszeichen: Schweigt der Anbieter länger als 15 Sekunden, sendet der Proxy einen SSE-Kommentar (OpenAI-Format) bzw. ein ping-Ereignis (Anthropic-Format). Die Leerlauf-Grenze Ihres Clients darf deshalb knapp bleiben.
  • Grenze: Die unscharfe Suche (RapidFuzz) findet im Strom nicht statt, weil bereits gesendeter Text nicht mehr korrigierbar ist. Greift das Fenster einmal fehl, sehen Sie ein Pseudonym statt des Originals. Das ist ein Schönheitsfehler, kein Datenabfluss: Die datenschutzkritische Richtung (Ihre Daten zum Anbieter) wird nie gestreamt, sondern immer vollständig übersetzt, bevor etwas den Server verlässt.

Wiedergabe-Speicher (Replay) für Agenten-Schleifen

Agenten schicken bei jeder Runde den gesamten Verlauf erneut. Der Proxy merkt sich je Sitzung zu jedem übersetzten Block einen Hash der Client-Form und die zugehörige Upstream-Form (nur Pseudonyme, keine Originale), verschlüsselt im Tresor und mit derselben Ablaufzeit wie die Sitzung. Kommt ein Block wieder, geht er byte-gleich zum Anbieter:

  • Keine erneute Analyse alter Runden: Nur neue Nutzertexte und Werkzeugergebnisse durchlaufen die Erkennung. Das spart je Runde Sekunden und hält die Kosten der Stufe B klein.
  • Stabiler Prompt-Cache beim Anbieter: Der Anfang der Anfrage bleibt Zeichen für Zeichen gleich, Cache-Treffer bleiben erhalten.
  • Modellantworten unverändert: Text, Werkzeug-Eingaben und Denk-Blöcke der Vorrunde erreichen den Anbieter exakt so, wie er sie erzeugt hat. Das ist Voraussetzung für signierte Denk-Blöcke und für Modelle, die ihre eigene Vorgeschichte prüfen.
  • Voraussetzung: Dieselbe Sitzung über den Header X-Pseudo-Sitzung (z. B. je Unterhaltung oder je Gerät). Ohne Sitzungs-Header beginnt jede Anfrage neu, und der Speicher greift nicht.
  • Der Antwort-Header X-Pseudo-Replay zeigt Treffer/Abfragen; in einer laufenden Unterhaltung sollten alle Blöcke bis auf die neuesten Treffer sein. Beim Selbstbetrieb schaltet PSEUDO_PROXY_REPLAY=false den Speicher ab, PSEUDO_PROXY_KEEPALIVE_SEKUNDEN setzt das Lebenszeichen, PSEUDO_PROXY_PARALLEL (4) die Zahl gleichzeitiger Übersetzungen – weitere Anfragen warten, ohne den Dienst anzuhalten.

Medien-Regel: Bilder, PDF-Dokumente, Tonaufnahmen

Bilder, Bildschirmfotos, PDF-Dateien und Tonaufnahmen lassen sich nicht pseudonymisieren. Die Medien-Regel legt fest, was der Proxy mit solchen Blöcken macht – in Nutzernachrichten ebenso wie in Werkzeugergebnissen, im Anthropic-Format (image, document) und im OpenAI-Format (image_url, input_image, input_audio, file, input_file).

WertWirkung
durchlassen (Server-Standard)Die Blöcke gehen unverändert zum Anbieter – das Modell sieht Bilder und Dokumente im Original.
entfernenBilder, Tonaufnahmen und Dateiverweise werden durch einen kurzen Hinweis an das Modell ersetzt. Aus PDF-Dokumenten liest der Proxy den Text aus (höchstens 200.000 Zeichen), pseudonymisiert ihn und übergibt ihn als Textdokument; Titel, Kontext und cache_control bleiben. PDF-Dateien ohne auslesbaren Text (Scans) werden wie Bilder ersetzt.
abweisenDie Anfrage wird mit 400 abgelehnt, sobald sie einen solchen Block enthält.
nachweisNur Bilder mit gültigem Nachweis der Bildschwärzung für die Sitzung der Anfrage (X-Pseudo-Sitzung) gehen zum Modell, etwa Bildschirmfotos der Desktop-Erweiterung; alle anderen Blöcke wie bei entfernen.
schwaerzenWie nachweis, doch Bilder ohne Nachweis schwärzt der Proxy selbst mit der Sitzung der Anfrage (zählt als Bild, gleiche Obergrenze je Minute); gelingt das nicht, wird das Bild entfernt. Bilder als Adresse (URL) werden entfernt.

Es gilt die strengste Angabe aus Server (PSEUDO_PROXY_MEDIEN), Konto (medien in PUT /api/konto/einstellungen bzw. auf der Konto-Seite) und Anfrage (X-Pseudo-Medien). Text-Dokumente (document mit Textquelle oder Inhaltsblöcken) sowie Titel und Inhalt von search_result-Blöcken werden unabhängig von der Regel immer pseudonymisiert. Ersetzte Blöcke sind in jeder Runde gleich (stabiler Prompt-Cache); das Ergebnis eines ausgelesenen PDF-Dokuments liegt im Wiedergabe-Speicher. Das Betreiber-Protokoll hält die Anzahl fest, nie Inhalte.

Brücken-Werkzeuge: Werkzeuge, die selbst pseudonymisieren

Manche Werkzeuge arbeiten selbst über den Pseudonymisierer: Sie liefern ihre Ergebnisse bereits mit Ersatzdaten und setzen die Originale ein, bevor sie etwas schreiben oder eintippen – etwa eine Browser-Brücke oder die Desktop-Erweiterung. Läuft dieselbe Anwendung zusätzlich über den Proxy, würde er diese Ergebnisse ein zweites Mal analysieren und Pseudonyme von Pseudonymen bilden. Nennen Sie solche Werkzeuge deshalb im Header X-Pseudo-Bruecken (oder in der Servereinstellung PSEUDO_PROXY_BRUECKEN):

  • Werkzeugergebnisse dieser Werkzeuge reicht der Proxy unverändert an das Modell weiter. Bilder darin unterliegen weiter der Medien-Regel.
  • Werkzeugaufrufe an diese Werkzeuge gehen mit den Ersatzdaten an den Client, so wie das Modell sie erzeugt hat – das Werkzeug setzt die Originale selbst ein. Im Strom laufen ihre Eingaben deshalb ohne Sammeln durch.
  • Text des Modells personifiziert der Proxy wie immer: Der Mensch liest echte Namen, auch wenn sie aus einem Brücken-Werkzeug stammen.
  • Voraussetzung: Werkzeug und Proxy verwenden dieselbe Sitzung (Header X-Pseudo-Sitzung bzw. Feld sitzung der REST-API) und denselben API-Schlüssel. Nur dann kennt der Proxy die Zuordnung, mit der das Werkzeug ersetzt hat.

Die Muster vergleichen den Werkzeugnamen, wie er in der Anfrage steht; MCP-Clients bilden ihn meist als mcp__<Server>__<Werkzeug>. Tragen Sie nur Werkzeuge ein, die wirklich selbst pseudonymisieren – alle anderen Ergebnisse analysiert der Proxy weiterhin.

Englische Anweisungstexte

Agentische Anwendungen schicken lange englische System-Prompts mit. Die Erkennung ist auf deutsche Texte eingestellt; ohne Gegenmaßnahme hielte sie dort Satzanfänge und Allerweltswörter für Namen. In Absätzen, die eindeutig englisch sind, zählen deshalb die Treffer des deutschen Sprachmodells nicht, und Personen, Firmen und Orte aus der KI-Erkennung müssen wie ein Eigenname aussehen (großgeschriebenes Wort, das kein Allerweltswort ist). Kontaktdaten und Kennungen aus der KI-Erkennung müssen in jeder Sprache zur Form ihres Typs passen (eine E-Mail-Adresse enthält @, eine Kennung eine Ziffer). Muster-Erkenner, Sperrliste und Stufe B bleiben unberührt; deutsche und unklare Absätze laufen wie bisher durch die volle Erkennung. Echte Namen in englischen Texten („Please call John Smith“) werden weiterhin ersetzt. Produkt- und Firmennamen in Anweisungstexten bleiben mit den Klartext-Regeln lesbar (Themenfelder marken, produkte, software).

Claude Desktop und andere Desktop-Anwendungen im Gateway-Modus

KI-Desktop-Anwendungen, die ihre Modellaufrufe an ein eigenes Gateway im Anthropic-Format schicken können, arbeiten vollständig über den Pseudonymisierer. Für Claude Desktop („Third-Party Inference“, macOS und Windows) erzeugt die Seite Claude Desktop einrichten die fertige Konfiguration: als JSON-Datei zum Importieren, als Konfigurationsprofil für macOS und als Richtlinie für Windows. Chat, Cowork und Code laufen dann über POST /v1/messages; der Anbieter sieht System-Prompt, Eingaben, gelesene Dateien und Befehlsausgaben nur mit Ersatzdaten, die Antworten und Werkzeugaufrufe kommen mit den echten Werten zurück. Die Einrichtung Schritt für Schritt beschreibt die Anleitung zu Claude Desktop.

Über das GatewayAnmeldung mit Anthropic-Konto, nur Erweiterungen
Eingaben im Chatpseudonymisiertgehen im Klartext an den Hersteller
Eingebaute Werkzeuge (Dateien lesen, Befehle, Suche)Ergebnisse pseudonymisiert (X-Pseudo-Modus: voll)Ergebnisse im Klartext
BrowserBrowser-Brücke AlphaChrome als Brücken-WerkzeugBrowser-Brücke AlphaChrome
Freigegebene Ordner, Outlook-Postfach, OneDriveDesktop-Erweiterung als Brücken-WerkzeugDesktop-Erweiterung
Bilder, Bildschirmfotos, PDFMedien-Regel (empfohlen: entfernen)unverändert zum Hersteller
Antworten im Chatechte Namen und WerteErsatzdaten; Originale entstehen erst beim Schreiben und Eintippen
Websucheeigene Websuche des PseudonymisierersSuche des Herstellers
Abrechnung der Modelleeigener API-Schlüssel beim Anbieter (X-Pseudo-Cloud-Key)Abonnement beim Hersteller

Was die Konfiguration setzt (Schlüssel in der Schreibweise von Claude Desktop):

SchlüsselWert
inferenceProvider, inferenceGatewayBaseUrl, inferenceGatewayApiKeygateway, https://pseudonymisierer.de (ohne /v1), Ihr Pseudonymisierer-Schlüssel (als Authorization: Bearer)
inferenceCustomHeadersX-Pseudo-Sitzung (feste Sitzung des Geräts), X-Pseudo-Modus: voll, X-Pseudo-Medien: entfernen, X-Pseudo-Bruecken (eingetragene lokale Werkzeuge), X-Pseudo-Erlaubnis: Claude,Anthropic, X-Pseudo-Themen: marken,produkte,software, auf Wunsch X-Pseudo-Sperre (Anmeldename des Rechners, der in jedem Dateipfad steht) und für Kundenkonten X-Pseudo-Cloud-Key. Die Kopfzeilen mit X-Pseudo- wertet nur der Pseudonymisierer aus; zum Anbieter gehen sie nicht.
managedMcpServersBrowser-Brücke (alpha-chrome) und Desktop-Erweiterung (pseudonymisierer) als lokale Programme. Im Gateway-Modus lassen sich Erweiterungsdateien (.mcpb) nicht per Doppelklick installieren; lokale Werkzeuge brauchen dort Node.js und vollständige Pfade.
organizationInstructionsKurze Anweisung an das Modell: Namen und Kontaktdaten sind Platzhalter und werden unverändert verwendet.
disableEssentialTelemetry, disableNonessentialTelemetry, disableNonessentialServices, skipWebFetchPreflightKeine Fehlerberichte, Nutzungsstatistik und Zusatzabrufe an den Hersteller; keine Hostnamen abgerufener Seiten an den Hersteller. Im Formular abschaltbar.
coworkEgressAllowedHosts, inferenceModels, deploymentDisplayNameOptional: Hosts, die Werkzeuge der Anwendung abrufen dürfen; feste Modellliste (sonst fragt die Anwendung GET /v1/models ab); Anzeigename „Pseudonymisierer“ in der Seitenleiste.
# Dieselben Dateien per API oder Kommandozeile
curl https://pseudonymisierer.de/api/claude-desktop -H "X-API-Key: psk_live_…" -H "content-type: application/json" \
  -d '{"cloud_schluessel": "sk-ant-…", "system": "macos", "anmeldename": "anna",
       "node": "/usr/local/bin/node", "desktop_erweiterung": "/Users/anna/Pseudonymisierer/desktop", "ordner": ["/Users/anna/Documents"]}'
# Antwort: sitzung, konfiguration, dateien.json / dateien.mobileconfig / dateien.reg (Text; .reg als UTF-16LE mit BOM speichern), hinweise

pseudonymisierer claude-desktop --system windows --desktop-erweiterung "C:\Werkzeuge\Pseudonymisierer\desktop" --ausgabe .

Hinweise für den Betrieb:

  • Erste Anfrage einer Sitzung: Der System-Prompt der Anwendung ist lang und wird einmal vollständig analysiert; das dauert einige Sekunden. Danach greifen Zwischenspeicher und Wiedergabe-Speicher – Folgerunden kosten nur die Analyse neuer Texte, der Prompt-Cache des Anbieters bleibt stabil.
  • Sitzung je Gerät: Chat, Browser-Brücke und Desktop-Erweiterung tragen dieselbe Sitzung. Sie läuft nach 7 Tagen ohne Nutzung ab und entsteht beim nächsten Aufruf neu; löschen lässt sie sich jederzeit im Konto.
  • Werkzeuge erhalten echte Werte: Aufrufe an gewöhnliche Werkzeuge (Dateien schreiben, Befehle, Web-Abruf) personifiziert der Proxy vollständig – auch Adressen, die das Modell bildet. Erlauben Sie den Web-Abruf nur, wenn Sie ihn brauchen, und lassen Sie Werkzeugaufrufe in der Anwendung bestätigen.
  • Nicht verändert werden Werkzeugdefinitionen (Namen, Beschreibungen, Schemata) und das Feld metadata der Anfrage. Die Oberfläche der Anwendung zeigt und speichert Unterhaltungen lokal mit den echten Werten.
  • Verbrauch: Gezählt werden die übermittelten Zeichen je Anfrage. Agentische Anwendungen schicken in jeder Runde den gesamten Verlauf; planen Sie das Kontingent entsprechend.
  • Andere Anwendungen mit Gateway-Einstellung tragen dieselben Werte ein: Basis-URL https://pseudonymisierer.de, Ihren Schlüssel und die genannten Kopfzeilen.

Websuche und Web-Abruf (web_search, web_fetch)

Nutzt ein Client über /v1/messages die serverseitigen Anthropic-Werkzeuge web_search_* und web_fetch_* – auch das eingebaute WebSearch des Claude Agent SDK stellt dafür eine eigene Anfrage mit dem Server-Werkzeug über den Proxy –, führt der Pseudonymisierer Suche und Abruf selbst auf seinem Server in Deutschland aus (Standard, sobald der Betreiber eine Suchinstanz eingerichtet hat). Kein Suchbegriff und keine Adresse erreicht dann über das Cloud-Modell einen Suchanbieter; das Modell bekommt nur pseudonymisierte Ergebnisse zu sehen. Der Proxy tauscht die Server-Werkzeuge gegen gleichnamige eigene Werkzeuge, ruft das Modell in einer Schleife auf, bis es fertig ist, und liefert dem Client das gewohnte Anthropic-Format – Clients und SDKs brauchen keine Anpassung.

  • Suchtext bereinigen: Platzhalter für Firmen (juristische Personen; Firmen ohne Rechtsform nur mit Firmen-Schalter alle), Orte und Domains der Sitzung werden vor der Suche in die echten Namen zurückübersetzt – so findet die Suche die richtige Firma. Platzhalter für Personen, Namensbestandteile, Straßen, E-Mail-Adressen, Telefonnummern, Kennungen und Begriffe der Sperrliste werden entfernt und nie zurückübersetzt; E-Mail-Adressen und Telefonnummern aus Mustern fallen zusätzlich heraus. Das Betreiber-Protokoll hält je Suche fest, wie viele Begriffe je Typ zurückübersetzt oder entfernt wurden (ohne Inhalte).
  • Suche: eine SearXNG-Metasuche auf dem eigenen Server (nur intern erreichbar; DuckDuckGo, Brave, Qwant, Startpage, Mojeek, Wikipedia; Sprache de-DE). Die Suchmaschinen sehen nur die bereinigte Anfrage von der Server-IP, keine Nutzerkennung. max_uses, allowed_domains und blocked_domains des Clients gelten wie beim Anbieter; zusätzlich werden Pseudonym-Domains der Sitzung ausgefiltert. Je Konto sind 30 Suchen und Abrufe pro Minute möglich.
  • Ergebnisse pseudonymisieren: Titel, Auszug, Adresse und Datum jedes Treffers laufen mit derselben Sitzungszuordnung durch die volle Erkennung (Standard; schnell per Servereinstellung oder X-Pseudo-Modus), bevor das Modell sie sieht. Das Modell erhält sie als search_result-Blöcke mit Zitaten; der Client bekommt web_search_tool_result mit echten Titeln und Adressen, encrypted_content ist der mit dem Tresor-Schlüssel versiegelte, bereits pseudonymisierte Treffer.
  • Web-Abruf: web_fetch lädt die Adresse vom Server – nur http/https, keine privaten Netze (auch nicht über Weiterleitungen), robots.txt wird beachtet, Zeit- und Größenlimit (20 s, 5 MB), HTML und PDF werden zu Text (60.000 Zeichen, max_content_tokens kürzt weiter). Wie beim Anbieter sind nur Adressen erlaubt, die in der Unterhaltung oder in Suchergebnissen vorkommen; Platzhalter-Adressen werden vorher zurückübersetzt. Der Seitentext wird pseudonymisiert an das Modell übergeben (document-Block mit Zitaten); der Client sieht web_fetch_tool_result mit dem echten Text.
  • Format für den Client: Die Blöcke erscheinen als server_tool_use (Kennung srvtoolu_ps_…), web_search_tool_result, web_fetch_tool_result und Zitate vom Typ web_search_result_location (encrypted_index versiegelt); usage.server_tool_use zählt web_search_requests und web_fetch_requests. Fehler kommen als web_search_tool_result_error/web_fetch_tool_result_error mit den Codes des Anbieters (max_uses_exceeded, url_not_allowed, too_many_requests …). Streaming liefert je Block eigene Ereignisse mit fortlaufenden Indizes und ein abschließendes message_delta; ohne Streaming eine zusammengesetzte Antwort. Nach 10 Modellrunden endet die Antwort mit pause_turn; schickt der Client den Verlauf zurück, läuft die Schleife weiter.
  • Folgerunden: Schickt der Client den Verlauf mit diesen Blöcken zurück, wandelt der Proxy sie in die Form zurück, die das Modell in der Vorrunde gesehen hat (tool_use/tool_result, byte-gleich dank Wiedergabe-Speicher und versiegelter Inhalte). Gemischte Runden – eigene Web-Werkzeuge und Client-Werkzeuge im selben Zug – funktionieren; verändertes encrypted_content wird wie beim Anbieter mit 400 abgewiesen. Innerhalb einer Unterhaltung sollte der Modus nicht gewechselt werden.
  • Schalter: Server-Standard PSEUDO_WEBSUCHE_STANDARD (eigen), Kontoeinstellung „Websuche“ (Konto-Seite, PUT /api/konto/einstellungen mit websuche) und je Anfrage der Header X-Pseudo-Websuche: eigen|anthropic. Der Antwort-Header X-Pseudo-Websuche zeigt, was galt. Ohne Web-Werkzeuge in tools ändert sich nichts.
  • Modus anthropic (Suche beim Anbieter): Dann sucht das Modell mit dem Text, den es sieht – was nicht per Klartext-Regel echt bleibt, geht als Pseudonym in die USA. Der Proxy federt das ab: Systemhinweis (Platzhalter nicht als Suchbegriffe verwenden), Pseudonym-Domains der Sitzung als blocked_domains (nicht bei allowed_domains des Clients), Warnung im Header X-Pseudo-Warnung und Protokolleintrag, wenn ein server_tool_use ein Pseudonym enthält; Server-Blöcke und Zitate bleiben in beide Richtungen unverändert. Für Recherchen zu Marken, Produkten oder der eigenen Firma helfen dort die Klartext-Regeln (Erlaubnisliste, Themenfelder, Firmen-Schalter juristisch).

MCP-Server

Streamable-HTTP-Endpunkt: https://pseudonymisierer.de/mcp-server/mcp mit Header X-API-Key.

claude mcp add --transport http pseudonymisierer https://pseudonymisierer.de/mcp-server/mcp --header "X-API-Key: psk_live_…"

# .mcp.json / Claude Desktop
{ "mcpServers": { "pseudonymisierer": { "type": "http", "url": "https://pseudonymisierer.de/mcp-server/mcp",
                                        "headers": { "X-API-Key": "psk_live_…" } } } }
WerkzeugZweck
pseudonymisieren(text, sitzung?, modus?, erlaubnisliste?, sperrliste?, llm?, schnell?)Text → Pseudonyme (Treffer ohne Originale)
personifizieren(text, sitzung, fuzzy?)Pseudonyme → Originale
pseudonymisieren_datei(pfad, …) / personifizieren_in_datei(text, sitzung, zielpfad)Dateibasiert – für Cloud-Agenten, die den Klartext nie sehen sollen (nur bei eigener Installation sinnvoll)
pseudonymisieren_tabelle, personifizieren_tabelleListen von Datensätzen
sitzung_info, sitzungen_liste, sitzung_loeschenVerwaltung
fehler_melden(art, sitzung?, text?, stelle?, typ?, kein_personenbezug?, anfrage_id?, quelle?, beschreibung?)Fehler der Pseudonymisierung melden – text und stelle so, wie das Modell sie sieht (Ersatzdaten); die Originale stellt der Dienst intern über die Sitzung her (siehe Fehler melden)

Wichtig: Ruft ein Cloud-Modell pseudonymisieren mit Klartext auf, hat es die Daten bereits gesehen. Das Werkzeug gehört in lokale Orchestrierung (eigene Skripte, n8n) oder vor das Modell (Proxy) – oder in die Desktop-Erweiterung, die den Klartext gar nicht erst an das Modell gibt.

Desktop-Erweiterung (macOS und Windows)

Die Desktop-Erweiterung ist ein MCP-Bundle (.mcpb) für KI-Desktop-Anwendungen wie z. B. Codex und Claude Desktop. Sie läuft lokal auf Ihrem Rechner und stellt der Anwendung Werkzeuge bereit, die Ordner, Dateien, Postfach und Cloud-Ablage nur in pseudonymisierter Form übergeben und beim Schreiben, Verschieben oder Umbenennen die Originale lokal wieder einsetzen. Erkennung und Zuordnung übernimmt der Pseudonymisierer (unser Server oder Ihre eigene Installation); die KI-Anwendung sieht Klartext nie – auch nicht in Rückmeldungen und Fehlermeldungen. Pfade erscheinen mit ~ statt des Benutzerordners, der Anmeldename bleibt auf dem Rechner.

Anleitungen für Anwender: macOS · Windows. Download (Version 0.5.0): macOS · Windows. Installation in Claude Desktop (Anmeldung mit Anthropic-Konto): Datei doppelklicken oder unter Einstellungen → Erweiterungen → „Erweiterung installieren“. Claude Desktop über das Gateway und andere MCP-fähige Anwendungen (z. B. Codex, Cursor): das Bundle ist ein ZIP-Archiv – entpacken und den Server als lokalen MCP-Server eintragen, etwa node /Pfad/server/index.js /Pfad/zum/freigegebenen/Ordner mit den Umgebungsvariablen PSEUDO_API_KEY, optional PSEUDO_URL, PSEUDO_SITZUNG, PSEUDO_MS_CLIENT_ID; für Claude Desktop erledigt das die Einrichtungsseite. Danach den API-Schlüssel (Konto → API-Schlüssel), optional die Server-Adresse (bei eigener Installation) und die freigegebenen Ordner eintragen. Außerhalb dieser Ordner verweigert die Erweiterung jeden Zugriff.

WerkzeugZweck
ordner_auflisten(pfad?, sitzung?)Ordnerinhalt mit pseudonymisierten Datei- und Ordnernamen; ohne Pfad die freigegebenen Ordner. Liefert die Sitzungs-ID für alle Folgeaufrufe
datei_lesen(pfad, sitzung?, maxZeichen?)Textdatei (txt, md, csv, json, eml, html, xml, yaml …) pseudonymisiert lesen
datei_schreiben(pfad, text, sitzung?, ueberschreiben?)Text personifiziert speichern (Pfad und Inhalt werden zurückübersetzt)
datei_verschieben(von, nach, sitzung?)Sortieren und Umbenennen; pseudonymisierte Pfade werden in echte Pfade zurückübersetzt, Ziel-Ordner entstehen bei Bedarf
ordner_anlegen(pfad, sitzung?)Ordner anlegen
pseudonymisieren, personifizieren, sitzung_loeschenWie beim MCP-Server – für Texte, die die Anwendung aus anderen Quellen erhält, und zum Löschen der Zuordnung
fehler_melden(art, text?, stelle?, typ?, kein_personenbezug?, beschreibung?, sitzung?, anfrage_id?)Seit Version 0.3.0: Fehler an den Dienst melden (siehe Fehler melden) – Text und Stelle mit Ersatzdaten, so wie die Anwendung sie kennt; die Erweiterung ergänzt die feste Sitzung, ihre Version und die Anfrage-ID des letzten Aufrufs. Die Anwendung meldet nur, wenn Sie sie dazu auffordern
fenster_auflisten, bildschirm_lesen(fenster)Seit Version 0.4.0 (Computerbedienung, Stufe lesen): offene Fenster der erlaubten Programme und ihre Bedienelemente als Text, je Element eine Zeile wie - button "Senden" [ref=e12] – vollständig pseudonymisiert
fenster_aktivieren, anwendung_starten, element_klicken(ref, maustaste?, bestaetigt?), text_eingeben(ref, text, ersetzen?, bestaetigt?), taste_druecken, scrollen(richtung, ref?, menge?), warten_aufStufe bedienen: Programme über die Verweise bedienen; eingegebener Text wird lokal personifiziert. Folgenreiche Schritte (senden, löschen, kaufen, Eingaben in Terminals …) nur nach Zustimmung im Dialog der Erweiterung oder mit bestaetigt=true
bildschirmfotoFolgt mit der Bildschwärzung; bis dahin nur ein Hinweis

Computerbedienung: ab Werk aus (Einstellung PSEUDO_COMPUTER: aus, lesen, bedienen). Die Erweiterung liest und bedient nur Programme, die Sie unter PSEUDO_ANWENDUNGEN eintragen; Kennwortverwaltungen, Anmelde- und Sicherheitsdialoge, Systemeinstellungen und KI-Anwendungen sind immer gesperrt, Kennwortfelder werden nie gelesen oder beschrieben. Anhalten jederzeit mit der Datei ~/.pseudonymisierer/stopp oder per Tastenkürzel (macOS: Control + Option + Befehl gedrückt halten, Windows: Strg + Alt + Umschalt + S); das Protokoll ~/.pseudonymisierer/aktionen.log enthält keine Inhalte. macOS liest über die Bedienungshilfen (Freigabe in den Systemeinstellungen nötig), Windows über UI Automation – beides ohne zusätzliche Installation. Einzelheiten in den Anleitungen für macOS und Windows.

Typischer Ablauf: „Sortiere die Dateien in Posteingang nach Kunden“ → die KI-Anwendung ruft ordner_auflisten auf und sieht z. B. Rechnung Jonas Butte.pdf, legt mit ordner_anlegen den Ordner Kunden/Jonas Butte an und verschiebt die Datei mit datei_verschieben. Lokal entsteht dabei Kunden/Thomas Müller mit der echten Datei – die Erweiterung setzt die Originale vor jedem Dateizugriff ein.

Feste Sitzung: Mit PSEUDO_SITZUNG (Einstellung „Feste Sitzung“) verwenden alle Werkzeuge dieselbe Sitzung, gleich welche das Modell angibt. Das ist die Voraussetzung dafür, dass die Erweiterung im Gateway-Modus als Brücken-Werkzeug arbeitet: Der Proxy reicht ihre Ergebnisse unverändert durch und setzt im Text des Modells die echten Werte ein. Ohne feste Sitzung führt das Modell die Sitzungs-ID aus den Ergebnissen mit.

Grenzen: PDF- und Office-Dateien werden verschoben, aber nicht gelesen. Postfächer und Ablagen anderer Anbieter (z. B. Google Workspace) folgen; bis dahin lassen sich Mails als .eml in einen freigegebenen Ordner exportieren. Nutzen Sie die eigenen Konnektoren einer KI-Anwendung (etwa deren Outlook-Anbindung) ohne Gateway, läuft deren Inhalt nicht durch den Pseudonymisierer – verwenden Sie stattdessen die Werkzeuge dieser Erweiterung oder richten Sie die Anwendung über das Gateway ein.

Microsoft-365-Konnektor (Outlook-Postfach, OneDrive)

Die Desktop-Erweiterung enthält einen Konnektor für Microsoft 365. Er liest Postfach und Cloud-Ablage über die Microsoft-Graph-Schnittstelle und übergibt Betreff, Absender, Vorschau, Mailtext, Datei- und Ordnernamen nur pseudonymisiert; Verschieben, Ordner anlegen und Antwortentwürfe laufen personifiziert zurück. Gesendet wird nie automatisch – Antworten landen als Entwurf im Entwurfsordner. Nachrichten- und Datei-IDs von Microsoft werden nicht an den Pseudonymisierer übermittelt.

Einrichtung (einmalig)

  1. App-Registrierung anlegen: Im Microsoft Entra Admin Center (entra.microsoft.com → Anwendungen → App-Registrierungen → Neue Registrierung) einen Namen wie „Pseudonymisierer Desktop“ vergeben. Unterstützte Kontotypen: „Konten in einem beliebigen Organisationsverzeichnis und persönliche Microsoft-Konten“. Keine Umleitungs-URI nötig.
  2. Öffentlichen Client erlauben: Unter Authentifizierung → Erweiterte Einstellungen → „Öffentliche Clientflows zulassen“ auf Ja stellen (Gerätecode-Anmeldung).
  3. Berechtigungen: API-Berechtigungen → Microsoft Graph → Delegiert: User.Read, Mail.ReadWrite, Files.ReadWrite, offline_access. Bei Firmenkonten ggf. Administratorzustimmung erteilen.
  4. Client-ID eintragen: Die „Anwendungs-ID (Client)“ aus der Übersicht in den Einstellungen der Erweiterung als Microsoft Client-ID hinterlegen; bei reinen Firmenkonten zusätzlich die Mandanten-ID (sonst „common“).
  5. Anmelden: In der KI-Anwendung „Melde mich bei Microsoft an“ sagen – das Werkzeug microsoft_anmelden zeigt einen Code und die Adresse https://microsoft.com/devicelogin. Code dort eingeben, fertig. Das Anmelde-Token liegt lokal unter ~/.pseudonymisierer/ (nur für Ihren Benutzer lesbar) und wird automatisch erneuert; microsoft_abmelden löscht es.
WerkzeugZweck
microsoft_anmelden / microsoft_status / microsoft_abmeldenGerätecode-Anmeldung starten, Anmeldestatus prüfen, lokales Token löschen
postfach_ordner(sitzung?)Ordner des Postfachs (Posteingang, Entwürfe, eigene Ordner) mit pseudonymisierten Namen und Anzahl ungelesener Mails
mails_auflisten(ordner?, anzahl?, nur_ungelesen?, sitzung?)Mails eines Ordners: Betreff, Absender, Datum, Vorschau – pseudonymisiert; liefert Sitzungs-ID
mail_lesen(id, sitzung?)Eine Mail vollständig (Text aus HTML gewonnen), pseudonymisiert
mail_verschieben(id, ziel_ordner, sitzung?) · postfach_ordner_anlegen(name, sitzung?) · mail_gelesen_markieren(id, gelesen?)Postfach aufräumen; Ordnernamen werden vor dem Zugriff personifiziert
mail_antwort_entwurf(id, text, alle?, sitzung?)Antwortentwurf mit personifiziertem Text im Entwurfsordner – nicht gesendet
ablage_auflisten(pfad?, sitzung?) · ablage_datei_lesen(pfad, sitzung?) · ablage_verschieben(von, nach_ordner, neuer_name?, sitzung?)OneDrive: Ordner pseudonymisiert auflisten, Textdateien lesen, Dateien verschieben oder umbenennen

Konto & Betreiber

Kundenkonto: Registrierung unter /registrieren mit Name, E-Mail, Passwort und gewünschtem Tarif (Test, Start, Business). Das Konto beginnt immer als Testzugang (14 Tage, 100.000 Zeichen); Start und Business schaltet der Betreiber innerhalb eines Werktags frei und sendet die Rechnung per E-Mail. Anmeldung an der Konto-Seite mit E-Mail und Passwort (POST /api/konto/anmelden liefert ein zwölf Stunden gültiges Sitzungs-Token, das wie ein API-Schlüssel im Header Authorization: Bearer … verwendet wird). Passwort ändern: POST /api/konto/passwort; Tarifwunsch: POST /api/konto/tarifwunsch; Schlüssel erneut kopieren: GET /api/konto/schluessel (die Konto-Seite zeigt nur Anfang und Ende); Schlüssel erneuern: POST /api/konto/schluessel; Klartext-Regeln, Websuche und Medien-Regel: GET/PUT /api/konto/einstellungen (siehe Klartext-Regeln).

Tarif intern ohne Verwaltungsrechte – für eigene Dienste des Betreibers, die den Pseudonymisierer wie ein Kunde nutzen: Anlegen mit POST /api/admin/mandanten {"name": "…", "email": "…", "tarif": "intern"} oder pseudonymisierer mandant anlegen --name … --tarif intern. Das Konto ist unbegrenzt und nutzt im Proxy ohne X-Pseudo-Cloud-Key die serverseitigen Modellschlüssel; sonst bleibt es getrennt wie jedes Kundenkonto (eigenes Geheimnis für die Pseudonyme, nur eigene Sitzungen, keine Admin-API, keine Inhalte im Betreiber-Protokoll). GET /api/konto nennt unter nutzung.tokens die Tokens der Anbieter im Monat, getrennt nach server (serverseitiger Schlüssel, Kosten beim Betreiber) und eigen – je eingabe, ausgabe, cache_schreiben, cache_lesen und summe, gezählt aus den Antworten auch im Datenstrom und über alle Runden der eigenen Websuche (bei OpenAI im Datenstrom fordert der Proxy die Nutzung selbst an). Eine Obergrenze für Tokens über den serverseitigen Schlüssel setzt der Betreiber mit PATCH /api/admin/mandanten/{id} {"token_grenze": 2000000} oder pseudonymisierer mandant aendern <id> --token-grenze 2000000 (0 = keine, ab Werk keine). Ist sie erreicht, antwortet der Proxy mit 402 und error.type token_grenze_erreicht, ohne das Modell aufzurufen; ein Aufruf, der sie überschreitet, läuft noch zu Ende.

Betreiber-Konten haben Tarif intern (unbegrenzt, serverseitige Cloud-Schlüssel) und Verwaltungsrechte: deploy/betreiber-schluessel.sh "Name" e-mail legt eines an, deploy/passwort-setzen.sh <konto-id> setzt das Passwort. Auf der Konto-Seite sehen Betreiber alle Konten mit Tarifwünschen („Freischalten“) und das Protokoll aller Pseudonymisierungen und Personifizierungen: Zeit, Aktion, Konto, Sitzung, Treffer, Dauer. Mit PSEUDO_PROTOKOLL_INHALTE=true werden für Betreiber-Aufrufe zusätzlich Ein- und Ausgabetext samt Zuordnung verschlüsselt mitgeschrieben (Aufbewahrung PSEUDO_PROTOKOLL_TAGE, Standard 7) – Kundeninhalte nie. API: GET /api/admin/protokoll, GET /api/admin/protokoll/{id}, DELETE /api/admin/protokoll.

Verbrauch: Auf der Konto-Seite sehen Betreiber außerdem den Verbrauch aller Konten je Monat – Aufrufe, Zeichen, Bilder und die Tokens der Modellanbieter, getrennt nach serverseitigem Schlüssel (Kosten des Betreibers, mit Summe über alle Konten) und eigenen Schlüsseln. Konten ab 80 % ihrer Token-Grenze und Konten, die den serverseitigen Schlüssel ohne Grenze nutzen dürfen, sind hervorgehoben; die Grenze lässt sich dort setzen. API: GET /api/admin/verbrauch?monat=JJJJ-MM (ohne Angabe der laufende Monat; monate nennt die Monate mit Daten). Mit PSEUDO_TOKENPREIS_EINGABE und PSEUDO_TOKENPREIS_AUSGABE (Euro je Million Tokens; optional PSEUDO_TOKENPREIS_CACHE_SCHREIBEN, PSEUDO_TOKENPREIS_CACHE_LESEN, sonst 1,25 × bzw. 0,1 × Eingabe) zeigt die Übersicht geschätzte Kosten – eine Schätzung, weil die Preise der Anbieter je Modell verschieden sind. Betreiber-Konten zählen keine Tokens.

Entitätstypen

TypBeispielErsatz (realistisch)
PERSONHerrn Dr. Thomas Müller · Müller · T. MüllerAnrede und Titel bleiben, Vor- und Nachname konsistent ersetzt, Geschlecht passend
ORGANIZATIONMüller & Söhne GmbHRechtsform bleibt; zugehörige Domain wird abgeleitet
ADDRESSHauptstraße 12, 80331 MünchenStraße, Hausnummer, PLZ (erste Ziffer optional erhalten), Ort
LOCATION (optional)Münchenanderer Ort; standardmäßig aus, Orte aus Adressen werden immer ersetzt
EMAIL_ADDRESSlisa.weber@mueller-soehne.deaus Ersatznamen abgeleitet, Domain der Ersatzfirma, Webmail-Domains bleiben
PHONE_NUMBER+49 171 2345678Länder- und Orts- bzw. Mobilfunkvorwahl und Format bleiben, die Teilnehmernummer samt Durchwahl ist neu
IBAN_CODE, CREDIT_CARDDE89 3704 0044 …gültige Prüfsumme, gleiches Land
DATE_OF_BIRTH03.05.1978konsistent verschoben, Format bleibt; ein bekanntes Geburtsdatum wird auch in anderer Form ersetzt, andere Daten bleiben unverändert
ID_NUMBERKundennummer KD-2024-0815gleiche Form (Ziffern/Buchstaben)
DE_TAX_ID, DE_TAX_NUMBER, DE_VAT_ID, DE_ID_CARD, DE_PASSPORT, DE_SOCIAL_SECURITY, DE_HEALTH_INSURANCE, DE_HANDELSREGISTERSteuer-ID, USt-IdNr., Ausweis, Pass, SV-Nr., KVNR, HRBgleiche Form
URL, IP_ADDRESS (optional)https://www.mueller-soehne.de/…Domain bekannter Firmen wird ersetzt; standardmäßig aus, damit Portal-Adressen funktional bleiben

Umgeformte Werte: IBAN, Telefon, Datum, Kennungen

Modelle schreiben strukturierte Werte oft in anderer Form zurück, als sie im Text standen. Der Dienst erkennt die folgenden Formen eines Ersatzwerts der Sitzung und setzt beim Personifizieren das Original in derselben Form ein – aus einer Ersatz-IBAN ohne Leerzeichen wird die Original-IBAN ohne Leerzeichen, aus einer Ersatznummer mit +49 die Originalnummer mit +49. Auf dem Hinweg bekommt ein schon bekannter Wert in jeder dieser Formen denselben Ersatzwert in der entsprechenden Form, auch im Schnellmodus.

TypErkannte Formen
IBANmit und ohne Leerzeichen oder Bindestriche, Viererblöcke, Groß- und Kleinbuchstaben: DE89 3704 0044 0532 0130 00 · de89370400440532013000
Telefonnational mit 0, international mit +49 oder 0049, mit (0), mit und ohne Leerzeichen, Klammern, Schräg- und Bindestriche: 089 123456 · +49 (0)89 123456 · (089) 123456 · 089/123456. Nummern anderer Länder in internationaler Form.
Datum03.05.1978 · 3.5.1978 · 03.05.78 · 1978-05-03 · 3. Mai 1978 · 3. Sept. 1978. Formen mit Schrägstrich (TT/MM oder MM/TT) sind mehrdeutig und werden nicht umgedeutet.
KennungenKunden-, Vertrags- und Steuernummern, Steuer-ID, USt-IdNr., Ausweis- und Kartennummern: Vergleich ohne Trennzeichen und ohne Groß-/Kleinschreibung, z. B. KD-2024-0815 · KD20240815 · kd 2024 0815.

Verglichen werden nur ganze Werte und nur mit Werten desselben Typs aus der eigenen Sitzung: Ein Betrag, eine Postleitzahl oder eine Rechnungsnummer wird nicht zur Telefonnummer, eine längere Zahl, in der ein Ersatzwert steckt, bleibt unverändert. Die Stufe liegt beim Rückweg nach dem genauen Abgleich und vor der unscharfen Suche und gilt für Text, JSON-Strukturen, Tabellen, Werkzeugaufrufe und den Proxy mit und ohne Streaming. Was ein Modell aus einem Ersatzwert berechnet (Initialen, Abkürzungen, ein Alter aus dem Geburtsdatum), ist keine Formvariante und bezieht sich weiter auf den Ersatzwert.

Modi & Optionen

OptionWirkung
modus: realistisch (Standard)Plausible Ersatzwerte – das Modell arbeitet mit natürlichem Text (Formulare, Anreden, Feldprüfungen).
modus: platzhalter[[PERSON_1]], [[FIRMA_1]], [[ADRESSE_1]], [[EMAIL_1]] … – strikt, Rückabbildung versteht auch [PERSON_1] oder „Person 1“.
schnell: trueNur Muster-Erkenner plus Wörterbuch der Sitzung (Millisekunden). Neue Namen werden nicht erkannt – Sitzung vorher mit dem Datensatz befüllen.
llm: trueZweite Erkennungsstufe mit lokalem Sprachmodell (ab Tarif Business). Fällt sie aus, arbeitet der Dienst weiter und meldet eine Warnung.
erlaubnislisteBegriffe, die nie ersetzt werden (Marken, Produkte, eigene Firma). Kontaktdaten und Kennungen (E-Mail, Telefon, IBAN, Ausweis …) lassen sich nicht freischalten; Personennamen bleiben nur mit Warnung und Protokolleintrag im Klartext.
sperrlisteBegriffe, die immer ersetzt werden: "Projekt Phoenix=ORGANIZATION" – auch im Schnellmodus und vor jeder Erlaubnis.
themenfeldermarken, produkte, software, normen, medizin: Begriffe, die das KI-Modell diesen Feldern zuordnet, bleiben im Klartext und heben überlappende Namens-Treffer auf (nur mit KI-Erkennung, nicht im Schnellmodus).
firmenjuristisch: Firmen mit Rechtsform (GmbH, AG, UG, KG, e. V. …) samt Firmenkern bleiben im Klartext, Firmen ohne Rechtsform („Schreinerei Huber“) werden weiter ersetzt. alle: jede als Organisation erkannte Firma bleibt – Achtung, Namen von Einzelunternehmen sind oft personenbezogen; als Person erkannte Namen bleiben geschützt.
orteAlleinstehende Orte ersetzen (true/false, sonst Konto- bzw. Server-Standard); Orte in Adressen werden immer ersetzt.
entitaetenEigene Auswahl der Typen, z. B. zusätzlich LOCATION oder URL.
fuzzy (Personifizieren)Unscharfe Rückabbildung für leicht veränderte Schreibweisen (Standard an; für Tabellen aus).

Klartext-Regeln je Konto

Auf der Konto-Seite oder per GET/PUT /api/konto/einstellungen legen Sie dauerhaft fest, was trotz Erkennung im Klartext bleibt – vor allem, damit ein Cloud-Modell Marken, Produkte, Fachbegriffe und auf Wunsch Ihre Firmennamen verwenden kann, etwa für Websuchen. Die Regeln gelten serverseitig für alle Schnittstellen Ihres Schlüssels: REST (auch /api/struktur/* und /api/tabelle/*), MCP, OpenAI- und Anthropic-Proxy. Angaben je Anfrage (Parameter oder Proxy-Header) ergänzen sie: Listen kommen dazu, Schalter überschreiben. Betreiber setzen die Regeln eines Kontos über PATCH /api/admin/mandanten/{id} (Feld einstellungen); für den Master-Schlüssel gelten die Servervariablen PSEUDO_ERLAUBNISLISTE, PSEUDO_SPERRLISTE, PSEUDO_THEMENFELDER und PSEUDO_FIRMEN_KLARTEXT.

Rangfolge: 1. Sperrliste (Anfrage, Konto) vor allem anderen, auch im Schnellmodus und in Werkzeugergebnissen. 2. Kontaktdaten und Kennungen aus Mustern (E-Mail, Telefon, IBAN, Kreditkarte, Geburtsdatum, Ausweis, Steuer-ID …) sind nie freischaltbar. 3. Erlaubnisliste (Anfrage, Konto); Personennamen darin bleiben nur mit Warnung und Protokolleintrag im Klartext. 4. Themenfelder. 5. Firmen-Schalter. 6. Die Erkennung selbst.

DSGVO-Hinweis zu Firmennamen: Firmennamen von Einzelunternehmen enthalten oft den Namen des Inhabers („Schreinerei Huber“) und sind dann personenbezogen. Der Schalter juristisch lässt deshalb nur Firmen mit Rechtsform stehen; alle gibt jede als Organisation erkannte Firma frei – prüfen Sie, ob das für Ihren Datenbestand vertretbar ist. Was die Erkennung als Person meldet, bleibt in beiden Stufen geschützt.

Verlauf und Transparenz: Regeländerungen wirken nur auf neue Texte; laufende Sitzungen behalten frühere Zuordnungen, und der Wiedergabe-Speicher des Proxys hält alte Runden byte-gleich. Jede Antwort zeigt im Feld im_klartext (REST, MCP) bzw. im Header X-Pseudo-Klartext (Proxy), wie viele Treffer wegen Erlaubnis, Themenfeld oder Firmen-Schalter im Klartext blieben; das Betreiber-Protokoll führt dieselben Zahlen und jede Regeländerung.

Restprüfung: Was steht noch im Klartext?

Nach jeder Pseudonymisierung über /api/pseudonymisieren, /api/struktur/pseudonymisieren und /api/tabelle/pseudonymisieren prüft der Dienst die Ausgabe auf Begriffe der Sperrliste (Server, Konto, Anfrage) und auf bekannte Originale der Sitzung – auch in anderer Schreibweise: Groß-/Kleinschreibung, Umlaut oder Umschrift (ä/ae, ö/oe, ü/ue, ß/ss), Akzente, Trennzeichen und übliche Endungen („Müllers“, „Schmidts“). Strukturierte Werte (IBAN, Telefon, Datum, Kennungen) werden in jeder Form gefunden. Das Ergebnis steht im neuen Feld restpruefung; alle übrigen Felder bleiben, wie sie sind:

"restpruefung": {"bestanden": false, "begriffe": 42,
  "treffer": [{"begriff": "Lindenquell", "typ": "SPERRLISTE", "schreibweise": "Lindenquells", "anzahl": 1}]}

Streng: Mit "streng": true im Körper (oder Header X-Pseudo-Streng: 1) kommt bei einem Fund statt der Ausgabe der Fehler 422 mit code und error.code restpruefung_fehlgeschlagen; die Fundstellen stehen im Feld restpruefung, die Meldung selbst nennt keine Begriffe. Im Proxy gilt dasselbe mit dem Header X-Pseudo-Streng für die ganze ausgehende Fassung.

Was die Prüfung nicht sehen kann: Bilder, Tonaufnahmen, Dateien und PDF-Dokumente als Binärdaten. Im strengen Modus gilt für sie dasselbe wie für einen Fund: Mit der Medien-Regel durchlassen antwortet der Proxy mit 422 und error.type bzw. code medien_nicht_pruefbar, und nichts geht an den Anbieter (auch in Ergebnissen von Brücken-Werkzeugen). Ausnahme: ein Bild mit gültigem Nachweis der Bildschwärzung derselben Sitzung – es geht ohne den Nachweis hinaus. Mit schwaerzen, nachweis und entfernen ändert sich nichts, weil dann nichts Ungeprüftes hinausgeht; abweisen bleibt, wie es ist. Nicht geprüft werden die Werkzeugdefinitionen (tools: Namen, Beschreibungen, Schemata) – sie stammen von der Anwendung, nicht aus Ihren Daten, und Standardbeschreibungen enthalten oft Ortsnamen wie „Europe/Berlin“. Gehören eigene Begriffe hinein, bitte dort selbst vermeiden.

Gegen Fehltreffer: nur ganze Wörter („Ulm“ nicht in „Ulmen“); Begriffe unter vier Zeichen nur in genau der bekannten Schreibweise und ohne Endung; Namen nur groß geschrieben oder in Bezeichnern wie thomas.mueller84 („klein“ ist nicht der Nachname „Klein“); Namen, die zugleich Allerweltswörter sind, nicht; Begriffe, die zugleich Ersatzwert der Sitzung sind, nicht. Was Erlaubnisliste, Themenfelder oder Firmen-Schalter bewusst stehen lassen, und Tabellenspalten vom Typ KEEP zählen nicht; die Sperrliste gilt immer. Der Abgleich ist linear in der Textlänge (gemessen etwa 0,6 s je Million Zeichen bei 18.000 Einträgen in der Sitzung). Die gefundenen Begriffe gehen nur an Sie zurück; das Betreiber-Protokoll und das Fehlerjournal halten höchstens Anzahl und Typ fest.

Sitzungen

Eine Sitzung ist die Zuordnungstabelle Original ⇄ Pseudonym samt Teilstücken (Nachname, Vorname, Firmenkern, Straße, Ort, Domain). Sie wird mit einem Schlüssel verschlüsselt, der aus dem Server-Geheimnis abgeleitet ist, läuft nach 7 Tagen ohne Nutzung ab und kann jederzeit gelöscht werden. Sitzungen sind strikt Ihrem Konto zugeordnet. Empfehlung: eine Sitzung je Vorgang (E-Mail-Thread, Agentenaufgabe, Datei), die ID bei sich speichern und nach Abschluss löschen. Zur Sitzung gehört beim Proxy auch der Wiedergabe-Speicher (Hashes der Client-Form und die zugehörigen pseudonymisierten Upstream-Formen); er wird mit der Sitzung gelöscht.

Sitzungskennung: Die Kennung (Feld sitzung, Header X-Pseudo-Sitzung, Parameter sitzung der MCP-Werkzeuge) wird nicht pseudonymisiert – sie gehört zu den Metadaten und kommt unverändert beim Dienst an. Verwenden Sie deshalb eine zufällige Kennung (die der Dienst bei der ersten Anfrage vergibt, oder eine UUID) oder lassen Sie eine ableiten: POST /api/sitzungen/kennung mit {"text": "Vorgang 4711"} liefert für Ihr Konto zu gleichem Text immer dieselbe Kennung (s_ und 32 Zeichen; andere Konten erhalten andere). Der Text lässt sich daraus nicht zurückgewinnen und wird weder gespeichert noch protokolliert. So ordnen Sie gleiche Vorgänge gleichen Sitzungen zu, ohne eine eigene Regel zu erfinden. Nie Namen, E-Mail-Adressen, Telefonnummern, Dateinamen oder Kundennummern als Kennung verwenden.

Sieht eine Kennung nach einer personenbezogenen Angabe aus (Name, E-Mail-Adresse, Telefonnummer), arbeitet der Dienst weiter, antwortet aber mit einem Hinweis im Header X-Pseudo-Warnung (MCP-Werkzeuge: im Feld warnungen). Im Betreiber-Protokoll und im Fehlerjournal steht eine solche Kennung nur als Fingerabdruck.

Berechnete Werte: Was ein Modell aus einem Ersatzwert berechnet – Initialen, Abkürzungen, die Anrede aus dem Vornamen, das Alter aus dem Geburtsdatum –, bezieht sich auf den Ersatzwert und kommt so zurück; der Rückweg kann es keinem Original zuordnen. Lassen Sie sich Werte im Wortlaut geben und formen Sie sie erst bei sich um, etwa die Initialen aus dem personifizierten Namen. Ausgenommen sind umgeformte strukturierte Werte – eine IBAN ohne Leerzeichen, eine Telefonnummer mit +49, ein Datum als JJJJ-MM-TT, eine Kennung ohne Trennzeichen –: Sie erkennt der Rückweg und setzt das Original in derselben Form ein (siehe Umgeformte Werte).

Beträge ersetzt der Dienst nicht: Rechenergebnisse des Modells bleiben so richtig, bei Personal- und Gehaltsdaten erreichen die Beträge das Modell aber im Klartext (nur die Namen sind ersetzt). Wer das nicht möchte, lässt Beträge weg oder ersetzt eine Betragsspalte über spalten_typen als ID_NUMBER durch Ersatzzahlen – dann stimmen Rechnungen des Modells nicht mehr.

Fehler & Limits

StatusBedeutung
400Ungültiger Proxy-Header (z. B. X-Pseudo-Firmen), Liste zu groß für den HTTP-Kopf – größere Listen gehören ins Konto – oder Medien-Regel abweisen bei einer Anfrage mit Bild, PDF-Dokument oder Tonaufnahme
401Schlüssel fehlt, ist falsch oder gesperrt
402Testzeitraum abgelaufen bzw. Cloud-Schlüssel im Proxy fehlt; mit error.type token_grenze_erreicht: Token-Grenze des Kontos für den serverseitigen Schlüssel erreicht
404Sitzung unbekannt, abgelaufen oder gehört einem anderen Konto
422Ungültige Anfrage (z. B. fehlender Text, unbekannter Tarif)
429Taktlimit je Minute oder Monatskontingent erreicht – Antwort enthält Zahlen und Limit
TarifZeichen / MonatAufrufe / MinuteStufe B
Test (14 Tage)100.00020–
Start1 Mio.60–
Business10 Mio.300ja
Agentur50 Mio.900ja

Gezählt werden die übermittelten Zeichen je Anfrage (Content-Length). Die Nutzung sehen Sie live unter GET /api/konto.

Anfrage-ID: Jede Antwort trägt den Header X-Pseudo-Anfrage-ID (a_ und 12 Zeichen), auch Fehler der Schlüsselprüfung, der MCP-Server und Datenströme. REST-Fehler nennen die Kennung zusätzlich im Körper ({"detail": "…", "anfrage_id": "a_…"}); Fehler auf /v1/… bleiben im Format der Anbieter, dort steht sie nur im Header. Eine mitgeschickte Kennung übernimmt der Dienst nicht. Bei Netz- oder Zeitfehlern des Modellanbieters antwortet der Proxy mit 502 bzw. 504 im Format der Anbieter. Technische Fehler (Status ab 500) hält der Dienst in einem Fehlerjournal fest; melden Sie sie trotzdem mit der Anfrage-ID, wenn Sie eine Antwort wünschen.

Fehler melden

Bleibt ein Name stehen, wird ein Produktname ersetzt, kommt ein Pseudonym nicht zurück oder schlägt eine Anfrage fehl, melden Sie das direkt an den Dienst: im Konto (Abschnitt „Fehler melden“), mit dem MCP-Werkzeug fehler_melden (MCP-Server, Desktop-Erweiterung, AlphaChrome ab 0.3.1 – auch mit abgelaufenem Testzugang oder aufgebrauchtem Kontingent) oder per POST /api/meldungen mit API-Schlüssel oder Web-Sitzung. Sie müssen dafür keine Texte per E-Mail weiterreichen.

Was wir sehen: ausschließlich eine bereinigte Fassung – Ihren Ausschnitt vollständig pseudonymisiert, die betroffene Stelle als Form (Buchstaben als X/x, Ziffern als 9, z. B. Xxxxxxxxx-Xxxxxx) samt Nachbarwörtern, eine Diagnose der Erkennung (Position, Typ, Erkenner, Bewertung, Stufe und Regel je Treffer – ohne Text) und ob sich der Fehler mit Ersatzdaten nachstellen lässt. Originale sehen nur Sie selbst in Ihren eigenen Meldungen. Eine falsch ersetzte Stelle erscheint bei uns nur dann im Klartext, wenn Sie bestätigen, dass sie keine personenbezogene Angabe ist (kein_personenbezug), und sie weder wie ein Personenname noch wie Kontaktdaten oder eine Kennung aussieht. Einen nicht zurückübersetzten Ersatzwert (falsch_zurueck) sehen wir so, wie Sie ihn melden – nur wenn er keinem Original Ihrer Sitzung gleicht oder ähnelt, sonst ebenfalls als Form. Sitzungskennungen sehen wir nur als Fingerabdruck.

EndpunktZweck
POST /api/meldungenMeldung anlegen → 201 {"id": "f_…", "status": "offen"}
GET /api/meldungenEigene Meldungen mit Status, Antwort und Version
GET /api/meldungen/{id}Eigene Meldung samt Inhalt (Text, Stelle, Beschreibung), solange er aufbewahrt wird
DELETE /api/meldungen/{id}Meldung zurückziehen – die Inhalte werden sofort gelöscht
FeldInhalt
artfalsch_ersetzt, nicht_erkannt, falsch_zurueck, technisch, sonstiges
textAusschnitt, in dem der Fehler steckt (höchstens 4.000 Zeichen); leer bei technisch und bei sonstiges mit beschreibung (Wunsch, Hinweis zur Dokumentation)
fassungoriginal (Standard) oder pseudonymisiert – in welcher Form text und stelle vorliegen
stelleDie betroffene Zeichenfolge; muss wörtlich in text vorkommen. Pflicht bei den ersten drei Arten
typErwarteter Typ bei nicht_erkannt (PERSON, ORGANIZATION, LOCATION, … siehe Entitätstypen), optional
kein_personenbezugBestätigung bei falsch_ersetzt: Die Stelle ist keine personenbezogene Angabe
sitzungSitzungs-ID (6 bis 80 Zeichen: Buchstaben, Ziffern, Punkt, Strich, Unterstrich); Pflicht bei fassung: pseudonymisiert, hilfreich bei falsch_zurueck. Eine abgelaufene Sitzung hindert die Meldung nicht, die Sitzung eines anderen Kontos schon (403). Wir sehen die ID nur als Fingerabdruck
anfrage_idKennung der fehlgeschlagenen Anfrage aus X-Pseudo-Anfrage-ID, optional
quelleMeldende Anwendung und Version, z. B. desktop-erweiterung 0.3.0
beschreibungFreier Text, höchstens 1.000 Zeichen

Status: offen → in_arbeit → erledigt oder abgelehnt, mit antwort (unser Text an Sie) und version (Fassung des Dienstes, die den Fehler behebt); zurueckgezogen, wenn Sie die Meldung zurückziehen. Grenzen: 60 Meldungen je Konto und Tag; Meldungen zählen nicht auf das Zeichenkontingent und gehen auch mit abgelaufenem Testzugang. Aufbewahrung: Inhalte verschlüsselt, bis 14 Tage nach dem Abschluss, spätestens 90 Tage nach Eingang; danach bleiben nur Art, Status und Zeitpunkte.

# curl: Name nicht erkannt
curl https://pseudonymisierer.de/api/meldungen -H "X-API-Key: psk_live_…" -H "content-type: application/json" \
  -d '{"art":"nicht_erkannt","text":"Rückfragen bitte an Kowalczyk-Brandt.","stelle":"Kowalczyk-Brandt","typ":"PERSON","quelle":"meine-anwendung 1.2"}'

# Python: fehlgeschlagene Anfrage mit ihrer Kennung melden
import httpx
kopf = {"X-API-Key": "psk_live_…"}
r = httpx.post("https://pseudonymisierer.de/api/pseudonymisieren", headers=kopf, json={"text": text})
if r.status_code >= 500:
    httpx.post("https://pseudonymisierer.de/api/meldungen", headers=kopf, json={
        "art": "technisch", "anfrage_id": r.headers["x-pseudo-anfrage-id"], "quelle": "meine-anwendung 1.2"})

// PHP: falsch ersetzter Produktname (keine personenbezogene Angabe)
$ch = curl_init('https://pseudonymisierer.de/api/meldungen');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('PSEUDO_SCHLUESSEL'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['art' => 'falsch_ersetzt', 'text' => $ausschnitt, 'stelle' => 'Vitocal 250',
                                     'kein_personenbezug' => true, 'quelle' => 'shop-plugin 2.0'])]);
$meldung = json_decode(curl_exec($ch), true);  // ['id' => 'f_…', 'status' => 'offen']

Datenschutz & Aufbewahrung

  • Erkennung, Ersetzung und Zuordnung laufen vollständig auf unserem Server in Nürnberg; kein Text erreicht ein Cloud-Modell im Klartext.
  • Inhalte werden nicht protokolliert. Das Audit-Protokoll enthält Zeitpunkt, Sitzungs-ID und Trefferzahlen je Typ; Sitzungs-IDs, die nach einem Namen oder Kontaktdaten aussehen, nur als Fingerabdruck.
  • Klartext-Regeln (Erlaubnis- und Sperrliste, Themenfelder, Firmen-Schalter) liegen beim Konto. Personennamen in der Erlaubnisliste und Web-Werkzeugaufrufe mit Pseudonymen werden ohne Inhalte protokolliert.
  • Sitzungen samt Wiedergabe-Speicher des Proxys: verschlüsselt, 7 Tage, jederzeit löschbar. Konto: Name, E-Mail, Tarif, Schlüssel-Hash, Nutzungszähler.
  • Meldungen: Inhalte verschlüsselt, bis 14 Tage nach dem Abschluss, spätestens 90 Tage; wir sehen sie nur bereinigt. Fehlerjournal: technische Angaben ohne Anfrageinhalt, Fehlermeldungen verschlüsselt, 30 Tage.
  • Pseudonymisierung ist keine Anonymisierung (Art. 4 Nr. 5 DSGVO): Bei uns bleibt die Zuordnung für die Dauer der Sitzung bestehen, der Cloud-Anbieter erhält sie nicht. Ob die pseudonymisierten Daten für ihn noch personenbezogen sind, hängt nach dem Urteil des EuGH vom 4. September 2025 (C-413/23 P) davon ab, ob er die Personen mit seinen Mitteln bestimmen kann; für Sie als Verantwortlichen bleiben sie es (siehe Glossar). Auftragsverarbeitungsvertrag auf Anfrage.

Selbst betreiben

Der Dienst läuft als Docker-Container auf Linux-Servern oder Macs (Apple Silicon) im eigenen Netz; die Modelle (GLiNER, spaCy, optional Ollama) werden lokal geladen, Zuordnungen verlassen nie das Haus. Umgebungsvariablen tragen das Präfix PSEUDO_ (für Desktop-Anwendungen im Gateway-Modus u. a. PSEUDO_PROXY_MEDIEN und PSEUDO_PROXY_BRUECKEN); die Werkzeuge pseudonymisieren_datei/personifizieren_in_datei und serverseitige Cloud-Schlüssel stehen dann ebenfalls zur Verfügung. Lizenz, Einrichtung und Wartung: info@alpha-digital.de.