Integrate Anonimatum into your systems

Quick start

Three steps: create the API key, check it and anonymize your first document.

1. Create an API key in the App: Profile → API keys → «Generate API key». Copy it right away: it is not shown again. If you do not see the section, your plan does not include API access or your group administrator manages it.
2. Store it as an environment variable and check your group's plan with GET /api/public/plan.
3. Send the document to POST /api/public/ai/anonymize with the AI options you need. The response is the anonymized document in its original format.

export ANONIMATUM_API_KEY="tu_api_key"

# 1. Comprueba la clave: plan y cupo del grupo
curl -H "X-API-Key: $ANONIMATUM_API_KEY" \
  https://api.anonimatum.com/api/public/plan

# 2. Opciones de IA disponibles (rgpd, fechas, direcciones, qr…)
curl -H "X-API-Key: $ANONIMATUM_API_KEY" \
  https://api.anonimatum.com/api/public/ai/options

# 3. Primer anonimizado: PDF, Word, Excel o PowerPoint
curl -X POST https://api.anonimatum.com/api/public/ai/anonymize \
  -H "X-API-Key: $ANONIMATUM_API_KEY" \
  -F "file=@resolucion.pdf" \
  -F "aiOptions=rgpd,direcciones,qr" \
  -F "backgroundColor=black" \
  -F "textContent=none" \
  --output resolucion-anonimizada.pdf

Parameters of multipart endpoints are sent as form fields (-F). Usage is deducted from the plan of the key's group.

Authentication

X-API-Key

Header for machine-to-machine integrations. Each key belongs to a user and a group: it uses their permissions, plan and quota.

Authorization: Bearer

User session JWT, the same the App uses. Useful if you embed Anonimatum in an application with Politeia sign-in.

Isolation

A resource from another group returns 404, never 403: the API does not reveal whether it exists.

Revocation

Revoke a key in Profile → API keys; it stops working immediately. Never commit keys to code or repositories.

Limits

Technical limits in version 1.9.0 (per IP address or per request):

Each operation also deducts pages or documents from the group's plan. Check usage with GET /api/public/usage/current and /usage/remaining, or validate beforehand with POST /usage/validate-operation.

Errors

Errors use the standard format { errorCode, message, status }. The most common ones:

HTTP/1.1 403
Content-Type: application/json

{
  "errorCode": "PLAN_EXPIRED",
  "message": "Tu plan ha expirado. Contacta con el equipo de Politeia para renovarlo o activar un plan.",
  "status": 403
}

Branch on errorCode, not on the message text, which may change or be translated.

Webhooks

A webhook notifies your system with a signed JSON POST when a queue batch or a publication finishes. The notification never carries file names, titles, text or email addresses: only identifiers, statuses and, for batches, a download link used with your API key.

Events

Register with your API key

POST /api/public/webhooks returns the secret (whsec_…) only once; store it as an environment variable. A webhook created with an API key only receives that key's user events; the group administrator can create group-wide webhooks from the App panel. Also: GET, PUT and DELETE /{id}, POST /{id}/rotate-secret, POST /{id}/test and GET /{id}/deliveries. Up to 10 per group; the URL must be https.

curl -X POST https://api.anonimatum.com/api/public/webhooks \
  -H "X-API-Key: $ANONIMATUM_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://erp.ejemplo.es/anonimatum/webhook","events":["batch.completed","batch.failed"]}'

Verify the signature

Each notification carries the X-Anonimatum-Signature: t=<unix>,v1=<hex> header, where v1 is HMAC-SHA256 keyed with the full secret (including the whsec_ prefix) over «t.body». X-Anonimatum-Event, X-Anonimatum-Event-Id and X-Anonimatum-Delivery are also sent.

1. Read the raw body, without parsing or reformatting the JSON.
2. Split t and v1 from the header and reject the notification if t is more than 300 seconds away from your clock.
3. Compute HMAC-SHA256(secret, t + "." + body) as hex and compare it with v1 in constant time.
4. Deduplicate by X-Anonimatum-Event-Id: a retry carries the same id.
5. Answer 2xx within 5 seconds and process afterwards.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.ANONIMATUM_WEBHOOK_SECRET; // whsec_… completo

app.post("/anonimatum/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const parts = Object.fromEntries(
    (req.get("X-Anonimatum-Signature") ?? "").split(",").map((p) => p.split("=", 2))
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(400);
  const expected = crypto.createHmac("sha256", SECRET).update(t + ".").update(req.body).digest("hex");
  const given = Buffer.from(parts.v1 ?? "", "utf8");
  const ok = given.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected, "utf8"), given);
  if (!ok) return res.sendStatus(401);
  // Deduplica por req.get("X-Anonimatum-Event-Id") y procesa después.
  res.sendStatus(204);
});

Python (Flask)

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["ANONIMATUM_WEBHOOK_SECRET"].encode()  # whsec_… completo

@app.post("/anonimatum/webhook")
def webhook():
    body = request.get_data()  # cuerpo crudo, sin parsear
    header = request.headers.get("X-Anonimatum-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        abort(400)
    if abs(time.time() - t) > 300:
        abort(400)
    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        abort(401)
    # Deduplica por request.headers["X-Anonimatum-Event-Id"] y procesa después.
    return "", 204

Any non-2xx response (redirects are not followed) or one slower than 5 seconds counts as a failure. After the first attempt, retries happen at 1 min, 5 min, 30 min, 2 h and 6 h (6 attempts in total); the delivery log shows the status, HTTP code and next attempt.

If you would rather not expose an endpoint, poll batch status with GET /api/public/batch-jobs and download finished jobs with GET /api/public/batch-jobs/{id}/output.

MCP connector for AI assistants

Anonimatum exposes the same API as an MCP (Model Context Protocol) server. The assistant acts as your user and group after you authorize it in the App.

MCP server URL

https://gateway.politeiasoft.com/anonimatum/mcp

Claude

In claude.ai → Settings → Connectors, add a custom connector with the MCP URL and authorize access on Anonimatum's consent screen.

ChatGPT

In chatgpt.com → Settings → Connectors, add the MCP URL and complete the OAuth authorization. Custom connector availability depends on your ChatGPT plan.

Grok

In grok.com → Connectors, add the MCP URL and authorize access.

Cursor, Claude Code and other MCP clients

If the client supports OAuth with a local redirect, the URL is enough. Otherwise use the manual grant in the App (Profile → Connectors): it gives you a token and a ready-to-paste mcp.json.

Tools it exposes

• listar_operaciones — Lists the operations available to your user (same catalogue as the reference, without admin or internal endpoints).
• describir_operacion — Method, path, parameters and how to send files for an operation.
• ejecutar_operacion — Runs an operation; binary responses include a single-use download link.
• iniciar_subida_fichero — Returns a single-use upload URL, recommended for large documents (up to 250 MB).
• subir_fichero — Uploads a small file as Base64 in a single call.
• iniciar_subida_por_partes / subir_parte_fichero — Chunked upload for clients that cannot POST directly.

Irreversible operations (delete, de-anonymize) require the user's explicit confirmation in that turn. With an expired plan the assistant receives PLAN_EXPIRED and must relay the message without retrying. You can revoke each connection in Profile → Connectors.

Sample mcp.json (manual grant)

{
  "mcpServers": {
    "anonimatum": {
      "url": "https://gateway.politeiasoft.com/anonimatum/mcp",
      "headers": { "Authorization": "Bearer <token de la concesión manual>" }
    }
  }
}

SDK

Access on request

Official SDKs for Python (sync and asyncio) and TypeScript/JavaScript (Node 18+) built on this same reference. The repository is private: ask Politeia for access through the contact form. You can also generate a client from the OpenAPI file.

SDK repository (private)