For system integrators and firm IT
Automating Datenmaske Secure.
Four interfaces, one principle: everything runs on the same machine as the app. The API server binds 127.0.0.1 only — no document byte ever crosses a network interface.
The pipeline behind the API is identical to the UI: same detection, same fail-closed verification, same residual check after export.
- 100% on the device
- API on 127.0.0.1 only
- No upload, no cloud
- § 203 StGB: the document never leaves the machine
Four ways to integrate
REST API (local)
Detect and redact over HTTP on 127.0.0.1 — for scripts and integrations on the same machine.
Hot folder
Watch a folder: new files flow into review automatically — or, in “Auto” mode, straight into a fail-closed export.
Explorer context menu
Right-click a PDF → “Schwärzen mit Datenmaske” — open from any folder with one click.
MSI + GPO
Deploy via group policy or Intune; central settings for updates, model download and the hot folder.
Requirements
- Datenmaske Secure is installed and running (the API and hot folder only work while the app runs; minimized to the tray is fine).
- An active license is present — without a user scope the hot folder deliberately does nothing.
- For scripts against the REST API: Windows with curl.exe (included since Windows 10) or PowerShell 5.1+.
Enabling the REST API
The API ships off. Enable it in Settings, per workstation; you choose the key yourself (it is not generated) and it stays local to the app.
- Settings → System → “Local REST API”.
- Enter a port (default 47190) and an API key of your choosing. Without a key the server refuses to start at all (fail-closed).
- Click “Start”. The status turns active and the API is reachable.
- From the next app start onward the API starts automatically as long as key and switch are set.
First request (health)
curl.exe
curl.exe http://127.0.0.1:47190/api/v1/health PowerShell
Invoke-RestMethod http://127.0.0.1:47190/api/v1/health → {"status":"ok"} (no key required — liveness only, no document data)
Detect: POST /api/v1/detect
The request carries the PDF Base64-encoded. The response lists every finding with page number, box coordinates (PDF points, origin top-left), type, confidence and source (regex/model). These exact boxes are what you pass to redact next.
PowerShell
$key = "MEIN-SCHLUESSEL"
$pdf = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\Akten\gutachten.pdf"))
$det = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:47190/api/v1/detect -Headers @{ Authorization = "Bearer $key" } -ContentType "application/json" -Body (@{ pdfB64 = $pdf } | ConvertTo-Json)
$det.suggestions | Select-Object pageNumber, sensitivityType, confidence, source | suggestions[].pageNumber | Page, 1-based |
| suggestions[].bboxX / bboxY / bboxWidth / bboxHeight | Box in PDF points |
| suggestions[].sensitivityType | e.g. name, iban, birth_date |
| suggestions[].confidence | 0–99 |
| suggestions[].source | regex (rules/checksums) or ner (language model) |
Redact: POST /api/v1/redact
The detect boxes are grouped into pages. The response returns the redacted PDF (Base64) and a report; report.outputUsable is the trust signal: false means verification found a leftover and the file was discarded.
! Without human review: the script redacts only what detection finds. outputUsable confirms removal, not completeness. For files with names, free text or scans: spot-check the results or use the hot folder in “Review” mode.
PowerShell
# Boxen aus $det nach Seite gruppieren und schwärzen
$pages = $det.suggestions | Group-Object pageNumber | ForEach-Object {
@{
pageNumber = [int]$_.Name
rects = $_.Group | ForEach-Object {
@{ x = $_.bboxX; y = $_.bboxY; width = $_.bboxWidth; height = $_.bboxHeight }
}
}
}
$resp = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:47190/api/v1/redact -Headers @{ Authorization = "Bearer $key" } -ContentType "application/json" -Body (@{ pdfB64 = $pdf; pages = $pages; style = "black" } | ConvertTo-Json -Depth 6)
if ($resp.report.outputUsable) {
[IO.File]::WriteAllBytes("C:\Akten\gutachten_geschwaerzt.pdf",
[Convert]::FromBase64String($resp.pdfB64))
} else {
# Fail-closed: Ausgabe wurde verworfen — Funde prüfen (remainingPii)
$resp.report.remainingPii
} | pages[].pageNumber / rects[].x,y,width,height | Boxes from detect, 1-based pages |
| style | black (default), white, blur or pixelate |
| anonymize | Placeholders like [NAME_1] instead of bars |
| resiscan | Image-only PDF (text layer destroyed) |
| report.outputUsable / remainingPii | Verification passed / number of leftovers |
401 unauthorized · 400 bad body/base64 · 404 not found · 500 {error}
Three recipes
A · Route RA-MICRO / e-file exports into a hot folder
- In RA-MICRO, point the file export (PDF) at a network folder, e.g. \\firm-server\datenmaske\eingang.
- In Datenmaske: Settings → Folders → add that folder as a hot folder.
- Mode “Review” (default): every new file lands in the library for review; the original moves to the verarbeitet subfolder after processing.
- Mode “Auto” only for stocks of structured data: exports automatically, fail-closed, to redigiert/<name>_redigiert.pdf. Names and free text ALWAYS go to review — the automation is deliberately narrower than detection.
- SHA-256 dedup: the same file (even renamed) is never processed twice per user.
B · Nightly batch via script
- On the workstation running Datenmaske, create a scheduled task (PowerShell).
- The script below reads a folder, detects, redacts and checks outputUsable — discarded outputs stay visible in the rejected folder.
- Note: the script runs in the logged-in user’s context; the API listens on that user’s 127.0.0.1 only.
C · Roll out three workstations via MSI and GPO
- Put the MSI on a network share; assign it via GPO (Computer Configuration → Software Installation) or Intune — silent: msiexec /i Datenmaske-Secure-setup.msi /qn.
- For air-gapped networks use the full installer (Datenmaske-Secure-full.msi): it bundles the AI models; the first start downloads nothing.
- Place the ADMX templates centrally; policies under HKLM\SOFTWARE\Policies\Mokka\Datenmaske are read on every start: AutoUpdateMode (disable/notify/auto), BlockModelDownload (1 = block model download, for air-gap), HotFolderPath (central watch folder).
- Enter the license key on each workstation (app start or via key file); the Explorer context menu is enabled once per user in Settings → System.
B · Nightly batch via script
PowerShell · batch.ps1
$key = "MEIN-SCHLUESSEL"
$eingang = "C:\Akten\eingang"
$ok = "C:\Akten\geschwaerzt"
$nein = "C:\Akten\abgelehnt"
$archiv = Join-Path $eingang "verarbeitet"
New-Item -ItemType Directory -Force $ok, $nein, $archiv | Out-Null
Get-ChildItem $eingang -Filter *.pdf | ForEach-Object {
$pdf = [Convert]::ToBase64String([IO.File]::ReadAllBytes($_.FullName))
$det = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:47190/api/v1/detect -Headers @{ Authorization = "Bearer $key" } -ContentType "application/json" -Body (@{ pdfB64 = $pdf } | ConvertTo-Json)
$pages = @($det.suggestions | Group-Object pageNumber | ForEach-Object {
@{ pageNumber = [int]$_.Name; rects = @($_.Group | ForEach-Object {
@{ x = $_.bboxX; y = $_.bboxY; width = $_.bboxWidth; height = $_.bboxHeight } }) } })
$resp = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:47190/api/v1/redact -Headers @{ Authorization = "Bearer $key" } -ContentType "application/json" -Body (@{ pdfB64 = $pdf; pages = $pages } | ConvertTo-Json -Depth 6)
if ($resp.report.outputUsable) {
[IO.File]::WriteAllBytes((Join-Path $ok $_.Name),
[Convert]::FromBase64String($resp.pdfB64))
Move-Item $_.FullName (Join-Path $archiv $_.Name) -Force
} else {
Move-Item $_.FullName $nein -Force # fail-closed: bleibt sichtbar
}
} ! Without human review: the script redacts only what detection finds. outputUsable confirms removal, not completeness. For files with names, free text or scans: spot-check the results or use the hot folder in “Review” mode.
What the interfaces do not do
- No network access: the API binds 127.0.0.1 only. Driving it centrally from other machines is deliberately impossible — processing stays local per workstation.
- The API runs only while the app runs. There is no service mode without the app (yet).
- No “deliberately keep” in the API: values you reject in the UI still block the export over the API (strict fail-closed).
- Hot folder “Auto” exports only structured, checksum-verified data (e-mail, IBAN, credit card, tax ID, social insurance, passport and insurance numbers). Names, addresses and scans always go to human review.
- A CLI (datenmaske --in … --out …) exists in the project but is not part of the installer. The supported automation path for installed workstations is the REST API.
- One request = one PDF (Base64). Process large stocks sequentially; parallelism buys nothing — the server handles requests in order.
- Hot folders on network drives (UNC) are supported; for reliable “file complete” detection over unstable links we recommend a local sync folder.
- outputUsable proves the selected findings were removed and the residual check came back clean — not that detection found everything. Without spot-checking, a residual risk remains.
Distinction from the web API
This page describes the local desktop API. The web/cloud edition of Datenmaske (redact_pdf, detect_pii, get_report with an API key) is documented on the API documentation page — same ideas, different infrastructure. → /en/api-dokumentation
Further reading