Sessions & Mappings

Eine Session ist der Container, in dem Cortina das Mapping zwischen Originaltext und Pseudonym hält. Ohne Session keine Anonymisierung — und ohne dieselbe Session keine Deanonymisierung.

Was genau eine Session ist

• Ein UUID-Identifier (session_id).
• Ein Postgres-Eintrag mit Status (active / expired / destroyed) und expires_at. Postgres weiß nichts über Inhalte.
• Ein verschlüsseltes Envelope in Redis, das die Mapping-Tabelle zwischen Pseudonym ([PERSON_1]) und Originaltext (Hans Müller) enthält. Verschlüsselt mit AES-256-GCM, Schlüssel aus einem HKDF-abgeleiteten Session-Key vom MAPPING_ENCRYPTION_KEY.
• Eine TTL in Sekunden, die in Redis als Native-Expiry gesetzt ist.

Lifecycle

┌──────────┐    POST /v1/cortina/session     ┌──────────┐
│  client  │ ──────────────────────────────► │ ACTIVE   │
└──────────┘    { session_id, expires_at }   └────┬─────┘
                                                  │
                  POST /v1/cortina/anonymize      │
                  POST /v1/cortina/deanonymize    │  (TTL läuft …)
                                                  │
                                ┌─────────────────┼─────────────────┐
                                │                 │                 │
                                ▼                 ▼                 ▼
                          DELETE /session    TTL erreicht       (orphan)
                                │                 │
                                ▼                 ▼
                         ┌──────────┐       ┌──────────┐
                         │ DESTROYED│       │ EXPIRED  │
                         └──────────┘       └──────────┘
                         Mapping aus Redis gelöscht

Drei Endpoints reichen für den vollen Lifecycle:

• POST /v1/cortina/session — Session erstellen, leeres Mapping initialisieren. Status active.
• POST /v1/cortina/anonymize und POST /v1/cortina/deanonymize — arbeiten gegen ein bestehendes Mapping. session_id im Body.
• DELETE /v1/cortina/session/{id} — Session sofort zerstören und Redis-Mapping wipen. 204 No Content.

TTL-Defaults und -Bounds

Aus dem OpenAPI-Schema (SessionCreateRequest.ttl_seconds):

Feld	Wert
Minimum	60 (1 Minute)
Maximum	86_400 (24 Stunden)
Default	3600 (1 Stunde)

Die Server-Side clamped Werte außerhalb des Bereichs nicht stillschweigend zurecht — ttl_seconds: 0 oder ttl_seconds: 100000 gibt 422.

Was passiert, wenn die Session expired

• Anonymize-/Deanonymize-Call gegen eine expired Session: 404 session_not_found (Redis hat das Envelope geräumt). Der Caller muss eine neue Session erstellen — alte Pseudonyme aus der ersten Session sind dann nicht mehr auflösbar.
• Deanonymize-Call mit einem Pseudonym, dessen Mapping nie in dieser Session existierte: Der Pseudonym-Token bleibt im Output unverändert stehen. Cortina rät nichts.

TTL setzt das harte Limit

Wenn dein Workflow mehr als 24 h zwischen Anonymize und Deanonymize liegt, brauchst du eine Architektur-Änderung — nicht eine längere TTL. TTL ist die DSGVO-Garantie; sie bewusst lang zu drehen entwertet das Schutzversprechen.

Wann eine Session wiederverwenden

Wiederverwenden:

• Multi-Turn-Conversations mit dem LLM. Wenn „Anna” in Turn 1 als [PERSON_2] anonymisiert wurde, soll Turn 2 dasselbe Pseudonym benutzen — sonst „verliert” das LLM den Bezug zwischen den Turns.
• Dokument-Verarbeitung in Chunks. Alle Chunks eines Dokuments durch dieselbe Session schicken.
• Batch-Verarbeitung (siehe SDK-anonymizeBatch / anonymize_batch) — die SDKs machen das automatisch: eine Session für alle Inputs, die keine eigene session_id mitbringen.

Neu erstellen:

• Pro Anfrage / pro User-Session in deinem App-Modell, wenn die Anfragen inhaltlich unabhängig sind.
• Für Compliance-Workflows, wo das Mapping nach kurzer Zeit weg sein soll. TTL niedrig setzen + Session am Ende explizit destroyen.
• Wenn ein anderer User die Session bekommen würde — Sessions sind pro Tenant gescoped, aber mehrere Users innerhalb desselben Tenants würden Mappings sehen, was du wahrscheinlich nicht willst.

Sessions in den SDKs

Beide SDKs haben einen Convenience-Modus (anonymize(text) ohne explizite Session — eine Session wird automatisch erstellt) und einen expliziten Modus (createSession() / create_session()), den du dann für mehrere Anonymize-Calls in Folge nutzt.

→ TypeScript-SDK: Sessions → Python-SDK: Sessions