API-Dokumentation

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.

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 erneuern. Der Schlüssel wird serverseitig nur als Hash gespeichert.

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

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.

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.

Header

# 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: Der Proxy puffert die Antwort und sendet sie am Ende als reguläre Server-Sent-Events (ein Chunk plus Abschluss), damit Pseudonyme nicht über Chunk-Grenzen zerfallen. Für Chat-Oberflächen mit Live-Tippen ist das spürbar; für Agenten ist es unerheblich.

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_…" } } } }

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).

Entitätstypen

Modi & Optionen

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.

Fehler & Limits

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

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.
• Sitzungen: verschlüsselt, 7 Tage, jederzeit löschbar. Konto: Name, E-Mail, Tarif, Schlüssel-Hash, Nutzungszähler.
• Pseudonymisierung ist keine Anonymisierung (Art. 4 Nr. 5 DSGVO) – gegenüber dem Cloud-Anbieter sind die Daten faktisch anonym, bei uns bleibt die Zuordnung für die Dauer der Sitzung bestehen. 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_; 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.