PII Redactor
Text and image redaction service for sensitive data protection.
pii-redactor
servicepiiredactionpresidioUpdated 2026-11-03
Verified 2026-11-03
PII Redactor is a stateless FastAPI service that removes sensitive data from text and images. It uses Microsoft Presidio for text analysis and anonymization, and Presidio image redaction for OCR-based image masking. It also provides ADK-compatible batch masking for agent conversations.
Responsibilities
- Redact configured entity types from text payloads.
- Redact PII from uploaded image files.
- Mask ADK text batches with placeholder mappings that stay consistent across a conversation.
- Enforce Cosmos authentication and authorization before redaction.
- Expose health, readiness, metrics, and OpenAPI documentation endpoints.
Runtime
| Area | Details |
|---|---|
| Repository | cosmos-pii-redactor |
| Framework | FastAPI |
| Core libraries | presidio-analyzer, presidio-anonymizer, presidio-image-redactor |
| Default port | 8000 (2 workers by default) |
| State | Stateless |
| Telemetry | Cloud deployments run under opentelemetry-instrument, which reports to Azure Monitor through APPLICATIONINSIGHTS_CONNECTION_STRING |
API
| Method | Path | Purpose |
|---|---|---|
POST | /v1/redact-text | Redact PII from text. |
POST | /v1/redact-images | Redact PII from one or more images. Returns 204 when no PII is found. |
POST | /v1/adk/mask-text | Mask an ADK text batch and return masked items, the cumulative placeholder mapping, counters, and stats. Payloads over MAX_TEXT_BYTES return 413. |
GET | /healthz | Liveness probe. |
GET | /readyz | Readiness probe. |
GET | /metrics | Prometheus metrics. |
GET | /docs | OpenAPI UI. |
Authentication And Authorization
Requests require:
Authorization: Bearer <token>X-Org-Id: <org uuid>
The service validates JWTs through User Service JWKS. Service-token calls that act for an end user must include X-On-Behalf-Of-User-Id.
Authorization is checked through User Service PDP using the pii.redact action.
Configuration
Important environment variables:
| Variable | Purpose |
|---|---|
AUTH_ENABLED | Enables or disables auth checks (default true). |
USER_SERVICE_URL | User Service URL used for JWKS and PDP calls; required when auth is enabled. |
COSMOS_SERVICE_AUDIENCE | Expected service audience (default cosmos-pii-redactor). |
AUTHZ_ACTION | PDP action (default pii.redact). |
AUTHZ_TIMEOUT_SECONDS | PDP timeout (default 5 seconds). |
MAX_TEXT_BYTES | Maximum accepted text payload size (default 5 MiB). |
MAX_IMAGE_BYTES | Maximum accepted image payload size (default 9 MiB). |
DEFAULT_ENTITIES | Default Presidio entity set. |
DEFAULT_SCORE_THRESHOLD | Presidio score threshold (default 0.5). |
SPACY_MODEL | spaCy model used by Presidio (default en_core_web_lg). |
TESSERACT_LANG | OCR language for image redaction (default eng). |
OCR_DPI | OCR rendering DPI (default 200). |
OBSERVER_KAFKA_ENABLED, OBSERVER_KAFKA_TOPIC | Optional cost events for ADK masking sent to Observer (default disabled, topic observer-cost-events). |
Related Services
cosmos-mediagatewaycan call PII Redactor during screen-capture ingestion.cosmos-adk-v3calls/v1/adk/mask-textfor conversation PII masking.cosmos-user-v3provides JWKS validation material and PDP authorization.
Changelog
See PII Redactor Changelog for verified documentation and service-surface changes.