API-Referenz

Drei Schritte zu Ihrer ersten vollständigen Prüfung: Fügen Sie das Skript auf der Seite mit Ihrem Formular ein, senden Sie die Prüfung von Ihrem Server, und senden Sie Ihr Formular einmal ab. Erstellen Sie einen kostenlosen Schlüssel unter /signup — 10.000 Besucherprüfungen im Monat im kostenlosen Tarif, keine Karte.

// STEP 1 — HTML. The script on the page with your form, the class on the form itself.
// Your site sends a Content-Security-Policy (helmet's default does)? Add Maskbreak's
// hosts first, or the browser blocks the script: maskbreak.com/integrate.md#content-security-policy
<script async src="https://maskbreak.com/assets/sentinel.js"></script>
<form class="monocle-enriched" id="login-form">
  <input type="email" name="email" required>
  <button type="submit">Continue</button>
</form>

// STEP 2 — Your frontend script. It never holds the form on Maskbreak:
// a blocked or missing script only means the check gets less evidence.
document.getElementById('login-form').addEventListener('submit', async (event) => {
  event.preventDefault();
  const evidence = window.Sentinel ? await window.Sentinel.collect() : {};
  const response = await fetch('/your-login-endpoint', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    // evidence = { token, fingerprintEventId, tz }, already the API's names
    body: JSON.stringify({ email: event.target.email.value, ...evidence })
  });
  // Handle response.status and the next step in your existing login UI.
});

// STEP 3 — Node 18+ / Express backend.
// express, app and existingLoginHandler belong to your application.
// This check is NOT authentication and never creates a login session.
// MASKBREAK_MODE unset or 'watch' (start here): send every submission, also one
// with a missing field (the dashboard then says which half did not arrive),
// log the answer and always continue. 'enforce': stop block; hold review,
// missing evidence and errors (a used-up month continues, logged).
const MASKBREAK_MODE = process.env.MASKBREAK_MODE || 'watch';
app.use(express.json({ limit: '16kb' }));
app.use(express.urlencoded({ extended: false, limit: '16kb' }));
app.post('/your-login-endpoint', async (req, res, next) => {
  const body = req.body || {};
  // Form fields -> API names: monocle -> token, sentinel_fp -> fingerprintEventId,
  // sentinel_tz -> tz. Sentinel.collect() already returns the API names.
  const token = body.token || body.monocle;
  const fingerprintEventId = body.fingerprintEventId || body.sentinel_fp;
  const tz = body.tz || body.sentinel_tz;
  const missing = typeof token !== 'string' || !token ||
    typeof fingerprintEventId !== 'string' || !fingerprintEventId;
  let result = null, hold = null, monthUsedUp = false, status = null;
  if (!missing || MASKBREAK_MODE !== 'enforce') {
    try {
      const response = await fetch('https://maskbreak.com/v1/evaluate', {
        method: 'POST',
        signal: AbortSignal.timeout(5000), // example budget; measure your own
        headers: {
          'Authorization': 'Bearer ' + process.env.MASKBREAK_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ token, fingerprintEventId, tz, email: body.email })
      });
      status = response.status; // 401: MASKBREAK_API_KEY is empty or wrong
      if (!response.ok) {
        const refusal = await response.json().catch(() => null);
        // The month's checks are used up: let the action through unchecked
        // until the 1st (00:00 UTC) and log it, as watch mode does.
        if (response.status === 429 && refusal?.code === 'monthly_quota_exceeded') monthUsedUp = true;
        else throw new Error('Visitor check unavailable');
      } else {
        result = await response.json();
        // Production gate: never authorize from a fixture or personal test key.
        if (!result || result.test || result.sandbox || result.sample ||
            !['allow', 'review', 'block'].includes(result.decision)) {
          throw new Error('No production verdict');
        }
        if (result.decision === 'block') {
          hold = [403, { error: 'Action refused by policy' }];
        } else if (result.decision === 'review' || result.degraded || !result.device) {
          hold = [409, { next: 'step_up' }]; // implement a real step-up flow
        }
      }
    } catch {
      // Example temporary hold. Choose a fallback for each business action.
      hold = [503, { error: 'Check unavailable; try again shortly' }];
    }
  }
  if (missing) hold = [409, { next: 'step_up' }]; // enforce never trusts half a check
  // One line per check. Never log the key, browser tokens or form data.
  console.log('[maskbreak]', MASKBREAK_MODE, 'HTTP ' + (status ?? 'none'),
    result ? result.decision : monthUsedUp ? 'monthly_quota_exceeded' : 'no answer',
    hold ? 'enforce would return ' + hold[0] : 'enforce would continue');
  if (MASKBREAK_MODE === 'enforce' && hold) {
    return res.status(hold[0]).json(hold[1]); // never mint a session here
  }
  req.fraudCheck = result;
  return next(); // normal credential + authorization checks still run
}, existingLoginHandler);

Bevor Sie eine Entscheidung durchsetzen

Testen Sie normale Entscheidungen, fehlende Daten und die Wiederaufnahme unterbrochener Kundenvorgänge getrennt. Diese Leitfäden behandeln die Entscheidungen auf Anwendungsseite, die Ihnen eine API-Antwort nicht abnehmen kann.

• Entwerfen Sie Ihren Timeout-Fallback
• Planen Sie eine sichere Einführung

Rufen Sie den Sandbox-Endpunkt mit einem Klick auf. Keine Registrierung, kein API-Schlüssel — nur echte /v1/evaluate-Antwortstrukturen, die Sie in Ihren Code übernehmen können.

GET https://maskbreak.com/v1/evaluate/sample
   ?scenario=clean

{
  "auf ▶ Anfrage ausführen klicken": "um Live-JSON zu sehen"
}

Produktionsaufrufe nutzen POST /v1/evaluate mit einem token aus dem SDK und einem Authorization: Bearer sk_live_...-Header. Der Beispiel-Endpunkt liefert dieselbe Antwortstruktur, sodass Sie Ihre Parsing-Logik vor der Registrierung verdrahten können.

POST https://maskbreak.com/api/lookup
{ "ip": "185.220.101.34" }

{
  "auf ▶ Lookup ausführen klicken": "für ein Live-Urteil zu dieser IP"
}

So funktioniert es

Maskbreak nutzt einen dreistufigen Ablauf Client → Ihr Backend → Maskbreak-API, damit Ihr geheimer Schlüssel nie im Browser landet.

Authentifizierung

Alle Anfragen an /v1/evaluate müssen Ihren geheimen API-Schlüssel als Bearer-Token enthalten. Ihren Schlüssel finden Sie im Dashboard.

Schlüssel rotieren

Rotieren Sie in der Konsole (Integration → Rotieren, oder Einstellungen → API-Schlüssel; Ihr Passwort wird erneut abgefragt). Der neue Schlüssel funktioniert sofort, und der bisherige bleibt 24 Stunden gültig, damit ein Deployment ohne Lücke umstellen kann. Ist ein Schlüssel geleakt, beendet Alten Schlüssel jetzt widerrufen in den Einstellungen diese Frist sofort. Während der Frist zählen beide Schlüssel gegen dasselbe Stundenkontingent, und /v1/usage meldet für beide dieselben Werte.

Jedes Konto hat einen persönlichen sk_test_…-Schlüssel. Er führt die Live-Pipeline aus und speichert Testereignisse, ohne Live-Webhooks zu senden; seine Prüfungen zählen zu Ihrem Monatskontingent, er hat ein eigenes Stundenkontingent und umgeht die IP-Allowlist. Der öffentliche sk_test_sandbox-Schlüssel beantwortet ausschließlich deterministische Test-Token, ohne Konto und ohne gespeicherte Ereignisse. Eine IP-Allowlist für den Live-Schlüssel beschränkt /v1/evaluate, /v1/lookup und das Ausstellen eines Tokens über /oauth/token (400 unauthorized_client von jeder anderen Adresse), nicht /v1/usage.

OAuth 2.0 Client Credentials Neu

Tauschen Sie Ihre Konto-E-Mail und Ihren API-Schlüssel über den Standard-Grant client_credentials gegen ein kurzlebiges Bearer-Token. Das Token trägt Ihre Konto-ID, nie den Schlüssel selbst. Es gilt 60 Minuten, authentifiziert als Ihr aktueller Schlüssel seines Typs und ist an den Schlüssel gebunden, mit dem es ausgestellt wurde: Nach einer Rotation funktioniert es weiter, solange dieser Schlüssel gilt (die 24-Stunden-Frist des bisherigen Schlüssels); der Widerruf des bisherigen Schlüssels, eine zweite Rotation oder die Rotation des Testschlüssels beenden es sofort mit 401 — stellen Sie dann ein neues aus. Ein mit Ihrem sk_test_-Schlüssel ausgestelltes Token bleibt ein Test-Credential. API-Schlüssel funktionieren genau wie zuvor; das hier ist additiv.

curl -X POST https://maskbreak.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","client_id":"your@email.com","client_secret":"sk_live_..."}'

Verwenden Sie das zurückgegebene access_token überall dort im Authorization: Bearer-Header, wo ein API-Schlüssel akzeptiert wird. Token laufen ab; erneuern Sie sie durch Wiederholen des Austauschs. Der Schlüssel selbst verlässt Ihren Server nie.

Binden Sie das Maskbreak-SDK auf der Seite mit Ihrem Formular ein. Ein Script lädt beide Erkennungsschichten — Netzwerkintelligenz (VPN, Proxy, Rechenzentrum) und Geräteintelligenz (Antidetect-Browser, Bots, Manipulation) — und fügt beide in jedes Formular mit class="monocle-enriched" ein (am Formular selbst, nie an einem Eingabefeld).

<!-- Maskbreak SDK — network + device, on the page with your form -->
<script async src="loading..."></script>

<!-- class="monocle-enriched" on the form itself, never on an input -->
<form class="monocle-enriched" id="my-form">
  <!-- The SDK fills these in by itself: -->
  <input type="hidden" name="monocle"    value="eyJ..." /> // network
  <input type="hidden" name="sentinel_fp" value="a1b2..." /> // device
  <input type="hidden" name="sentinel_tz" value="Europe/Tallinn" /> // time zone
</form>

Ihre Website sendet eine Content-Security-Policy? Die Standardrichtlinie von helmet tut das und blockiert das Skript, bis Sie Ihre Direktiven um die eigenen Hosts des SDK ergänzen: script-src https://maskbreak.com https://mcl.maskbreak.com https://*.mcl.maskbreak.com https://mesu.maskbreak.com 'wasm-unsafe-eval', connect-src https://mcl.maskbreak.com https://*.mcl.maskbreak.com wss://mcl.maskbreak.com wss://*.mcl.maskbreak.com https://mesu.maskbreak.com und worker-src https://mesu.maskbreak.com blob:. Ein Teil, den die Richtlinie blockiert, bleibt leer, und die Prüfung läuft ohne ihn weiter. Der Integrationsleitfaden zeigt die Konfiguration für helmet.

Das SDK braucht etwa 1–2 Sekunden zum Laden und Erzeugen der Token. Wenn die Geräteschicht nicht laufen kann (z. B. weil ein gehärteter Browser sie blockiert), läuft die Auswertung allein über die Netzwerkschicht weiter.

Rufen Sie beim Absenden Sentinel.collect() auf — es wartet, bis die Geräteschicht fertig ist (höchstens 5 Sekunden; collect({ timeout: ms }) ändert das), und liefert { token, fingerprintEventId, tz }, bereits unter den Namen der API. Leiten Sie das an Ihr Backend weiter. Prüfen Sie vorher, ob window.Sentinel existiert, und halten Sie das Formular nie an, wenn das Skript fehlt oder blockiert ist. (Ein gewöhnlich abgesendetes Formular enthält stattdessen die versteckten Felder monocle, sentinel_fp und sentinel_tz: Ihr Server sendet sie als token, fingerprintEventId und tz.) Clientseitig gerenderte App (React, Next.js, Vue)? Es ist nichts weiter nötig: Das Skript hält ein verstecktes Formular bereit, sodass das Token auch für Formulare da ist, die Ihre App nach dem Laden der Seite rendert.

document.getElementById('my-form').addEventListener('submit', async (e) => {
  e.preventDefault();

  // Both layers (network token + device event id) and the time zone.
  // No script (blocked or still loading)? Send the form anyway.
  const evidence = window.Sentinel ? await window.Sentinel.collect() : {};

  // Forward them to your backend with the rest of the form data
  const res = await fetch('/your-backend-endpoint', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: e.target.email.value,
      ...evidence  // ← token, fingerprintEventId, tz: the API's own names
    })
  });
});

Rufen Sie das von Ihrem Backend-Server auf — nie aus dem Browser. Übergeben Sie das Token vom Client und Ihren geheimen API-Schlüssel.

Request-Body

Testen ohne Browser: Senden Sie ein deterministisches Test-Token — test_clean, test_vpn, test_proxy, test_datacenter oder test_tor —, um Ihre allow-/review-/block-Behandlung Ende-zu-Ende zu prüfen. Testaufrufe werden wie echte authentifiziert und ratenlimitiert, aber nie auf Ihr Monatskontingent angerechnet, gespeichert oder per Webhook gemeldet, und die Antwort trägt "test": true.

CI & Staging ohne Konto: Der öffentliche Sandbox-Schlüssel sk_test_sandbox akzeptiert dieselben test_*-Token und liefert dieselben deterministischen Strukturen — keine Registrierung, nichts berechnet, nichts gespeichert, belastet nie ein echtes Kontingent. Er beantwortet nur Test-Token (Live-Traffic braucht weiterhin Ihren echten Schlüssel) und ist pro IP ratenlimitiert. curl -X POST https://maskbreak.com/v1/evaluate -H "Authorization: Bearer sk_test_sandbox" -H "Content-Type: application/json" -d '{"token":"test_vpn"}'

Ihr eigener Testschlüssel (volle Pipeline): Jedes Konto hat zusätzlich einen persönlichen sk_test_…-Schlüssel (Einstellungen → API-Schlüssel), der anders als die Sandbox die komplette Live-Pipeline ausführt — echte Token, echte Geräteintelligenz, Ihre Regeln und Ausnahme-Pins eingeschlossen. Die Events, die er erzeugt, sind in der Konsole als Test markiert, aus Ihrer Statistik ausgenommen, lösen nie Webhooks aus, und die Antwort trägt "test": true. Seine Prüfungen zählen wie die Prüfungen der Konsole zu Ihrem Monatskontingent; die festen Test-Token oben nicht. Er hat sein eigenes Stundenkontingent und ist bewusst von der IP-Allowlist ausgenommen, damit CI und Laptops die Pipeline ausprobieren können, ohne Löcher in Ihre Produktionsbeschränkung zu schlagen.

// Your backend. Form fields -> API names: monocle -> token,
// sentinel_fp -> fingerprintEventId, sentinel_tz -> tz (collect() already uses them).
// Watch mode (start here) sends every submission, a missing field included.
const b = req.body || {};
let data = null;
try {
  const response = await fetch('https://maskbreak.com/v1/evaluate', {
    method: 'POST',
    signal: AbortSignal.timeout(5000),
    headers: {
      'Authorization': 'Bearer ' + process.env.MASKBREAK_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      token: b.token || b.monocle,
      fingerprintEventId: b.fingerprintEventId || b.sentinel_fp,
      tz: b.tz || b.sentinel_tz
    })
  });
  data = response.ok ? await response.json() : null;
} catch {
  data = null; // unavailable: watch mode continues
}

// data.decision → 'allow' | 'review' | 'block' (covers VPN, proxy,
// datacenter, Tor, antidetect, automation) — route on this
// data.reasons  → machine-readable why
console.log('[maskbreak]', data ? data.decision : 'no answer');

if (process.env.MASKBREAK_MODE === 'enforce' && data && data.decision === 'block') {
  return res.status(403).json({ error: 'Suspicious connection.' });
}

# Your backend (Flask shown): JSON from Sentinel.collect(), or a posted form.
# Form fields -> API names; watch mode (start here) sends every submission.
import os, requests

body = request.get_json(silent=True) or request.form
try:
    data = requests.post(
        "https://maskbreak.com/v1/evaluate",
        headers={"Authorization": "Bearer " + os.environ["MASKBREAK_API_KEY"]},
        json={
            "token": body.get("token") or body.get("monocle"),
            "fingerprintEventId": body.get("fingerprintEventId") or body.get("sentinel_fp"),
            "tz": body.get("tz") or body.get("sentinel_tz"),
        },
        timeout=5,
    ).json()
except (requests.RequestException, ValueError):
    data = None  # unavailable: watch mode continues

# data["decision"] → 'allow' | 'review' | 'block' — route on this
# data["reasons"]  → machine-readable why
print("[maskbreak]", (data or {}).get("decision", "no answer"))

if os.environ.get("MASKBREAK_MODE") == "enforce" and (data or {}).get("decision") == "block":
    return "403 Suspicious connection", 403

curl -X POST 'https://maskbreak.com/v1/evaluate' \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"token": "YOUR_BROWSER_TOKEN", "fingerprintEventId": "YOUR_DEVICE_EVENT", "tz": "Europe/Tallinn"}'

// Your backend: JSON from Sentinel.collect(), or a posted form.
// Form fields -> API names; watch mode (start here) sends every submission.
$in = json_decode(file_get_contents('php://input'), true) ?: $_POST;
$ch = curl_init('https://maskbreak.com/v1/evaluate');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 5,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('MASKBREAK_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'token' => $in['token'] ?? $in['monocle'] ?? null,
        'fingerprintEventId' => $in['fingerprintEventId'] ?? $in['sentinel_fp'] ?? null,
        'tz' => $in['tz'] ?? $in['sentinel_tz'] ?? null,
    ]),
]);
$data = json_decode((string) curl_exec($ch), true); // null when unavailable: watch mode continues

// $data['decision'] → 'allow' | 'review' | 'block' — route on this
// $data['reasons']  → machine-readable why
error_log('[maskbreak] ' . ($data['decision'] ?? 'no answer'));

if (getenv('MASKBREAK_MODE') === 'enforce' && ($data['decision'] ?? null) === 'block') {
    http_response_code(403);
    exit();
}

Senden Sie ein frisches, echtes Browser-Ereignis mit einem Live-Schlüssel an /v1/evaluate. device.customer_history zählt unterschiedliche verifizierte Ereignisse nur für Ihr Kundenkonto in den letzten 90 Tagen: erster und letzter Besuch, Wiederkehr und Anzahl zugehöriger Konten. Das Dashboard zeigt unter Ereignisse → Untersuchen die 50 zuletzt gesehenen Geräte. Die Historie beginnt mit Einführung dieser Funktion; alte Ereignisse werden nicht nachgetragen. Wiederholungen desselben Ereignisses zählen einmal. Fehlende Gerätedaten bedeuten keine Historie, nicht ein neues oder sicheres Gerät.

Für Kontoverknüpfungen muss Ihr Backend accountId aus seiner eigenen authentifizierten Sitzung bestimmen, niemals eine behauptete Konto-ID aus dem Browser übernehmen. Verwenden Sie eine pseudonyme ID, keine E-Mail-Adresse. Geteilte Geräte liefern Kontext, keinen Betrugsnachweis. Testschlüssel tragen nicht zu dieser neuen Historie bei. Die bisherigen Felder times_seen, returning und first_seen behalten ihre Bedeutung als gemeinsamer Zähler; verwenden Sie customer_history für Ihre eigenen Besucher.

// Your backend: accountId comes from YOUR authenticated session.
const response = await fetch('https://maskbreak.com/v1/evaluate', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY,
    'Content-Type': 'application/json'
  },
  signal: AbortSignal.timeout(8000),
  body: JSON.stringify({
    token: req.body.token,
    fingerprintEventId: req.body.fingerprintEventId,
    accountId: req.user ? String(req.user.id) : undefined,
    gpuEvidence: req.body.gpuEvidence // optional beta; otherwise omit
  })
});
if (!response.ok) throw new Error('Visitor check unavailable');
const result = await response.json();
const history = result.device?.customer_history;
// history: {visits, returning, first_seen, last_seen, accounts, window_days:90}
// Use your existing decision/review policy. History is not authorization.

// 1. Your backend requests a challenge using its LIVE API key.
// Protect your own route with session/CSRF checks and rate limits.
const response = await fetch('https://maskbreak.com/v1/device-evidence/challenge', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + process.env.MASKBREAK_API_KEY,
    'Content-Type': 'application/json' },
  signal: AbortSignal.timeout(6000),
  body: JSON.stringify({ fingerprintEventId: req.body.fingerprintEventId })
});
if (!response.ok) return res.status(200).json({ status: 'unavailable' });
return res.json(await response.json()); // challenge, expires_at, protocol

// 2. Browser, after your required consent/notice flow:
// Load https://maskbreak.com/assets/device-evidence.js?v=1 separately.
// Pass the challenge from YOUR backend; never send your API key here.
const gpuEvidence = challenge
  ? await MaskbreakGPU.collect(challenge)
  : { status: 'unavailable' };
// Forward only successful evidence with the SAME fingerprintEventId:
// gpuEvidence: gpuEvidence.features ? gpuEvidence : undefined
// If unavailable or your challenge route fails, continue normal checks.

// Browser: load /assets/browser-consistency.js?v=6 from maskbreak.com.
// Run only on an opted-in review step, after required notice/consent.
// Obtain the one-use challenge from YOUR authenticated backend route above.
const browserEvidence = challenge
  ? await MaskbreakBrowserConsistency.collect(challenge)
  : { status: 'unavailable' };
// Forward to YOUR backend with the same session-bound fingerprintEventId.
// Do not expose a Maskbreak API key in browser code.

// Backend: optional field in the existing POST /v1/evaluate JSON body:
// browserEvidence: browserEvidence.protocol ? browserEvidence : undefined
// Send either browserEvidence OR gpuEvidence for a device event, not both.
// Read result.device?.browser_consistency:
// {status:'inconsistent', experimental:true, source:'browser_reported',
//  affects_decision:false, findings:['browser_context'], checks:[...]}
// Keep the original decision/review policy. This report is not authorization.

Antwortobjekt

Ein erfolgreicher Aufruf liefert 200 OK mit dieser JSON-Struktur.

{
  "status": "success",
  "isSuspicious": true,
  "decision": "review",
  "risk_score": 65,
  "ip": "185.107.80.12",
  "country": "EE",
  "network": {
    "vpn": true,
    "proxy": false,
    "privacy_relay": false,
    "datacenter": true,
    "tor": false,
    "anonymous": true,
    "residential": false,
    "service": "PROTON_VPN"
  },
  "reasons": ["vpn_detected", "datacenter_asn"],
  "evaluated_in_ms": 126,
  "details": {
    "ip": "185.107.80.12",
    "cc": "EE",
    "vpn": true,
    "proxied": false,
    "anon": true,
    "dch": true,
    "service": "PROTON_VPN"
  }
}

{
  "status": "success",
  "isSuspicious": false,
  "decision": "allow",
  "risk_score": 0,
  "ip": "82.131.45.9",
  "country": "DE",
  "network": {
    "vpn": false,
    "proxy": false,
    "privacy_relay": false,
    "datacenter": false,
    "tor": false,
    "anonymous": false,
    "residential": true,
    "service": null
  },
  "reasons": [],
  "evaluated_in_ms": 118
}

Wie die Entscheidung zustande kommt

Die Engine gibt bei einem Proxy, Tor-Exit, erkannten Bot, Emulator oder einer Browsermanipulation block zurück. Ein VPN allein, ein Browser in einer virtuellen Maschine oder Apples iCloud Private Relay allein (der eine Proxy, der geprüft statt blockiert wird) ergibt review. Weitere Signale und Ihre Richtlinien können die endgültige Antwort beeinflussen. Ein Signal für einen Cloudserver oder ein anonymes Netzwerk allein führt nicht zu einer harten Sperre. Ihre Regeln und Ausnahmen können die Entscheidung überschreiben; engine_decision wird mitgeliefert, wenn eine Überschreibung die Entscheidung ändert, nicht bei jeder Antwort.

Eingeschränkte Antworten. Fehlende Netzwerkdaten führen zu degraded: true, ip: "unknown" und Netzwerkflags mit dem Wert false. Diese false-Werte bedeuten, dass die Daten nicht verfügbar sind, nicht dass die Verbindung unauffällig ist. Geräte- oder E-Mail-Signale, Regeln und Ausnahmen können weiterhin review oder block ergeben. Nur der reine, nicht verdächtige allow-Fallback wird aus den Auswertungszählern und Events ausgenommen; aussagekräftige Entscheidungen unterliegen der normalen Ereignis- und Verbrauchsverarbeitung. Authentifizierte Versuche verbrauchen weiterhin das stündliche Anfragekontingent.

Zusätzliche Flags. test: true bei jeder Antwort auf ein Test-Token oder einen Testschlüssel, sandbox: true, wenn der öffentliche sk_test_sandbox-Schlüssel verwendet wurde, sample: true bei /v1/evaluate/sample. /v1/lookup trägt zusätzlich ein additives network.cloud-Objekt, das den Anbieter nennt, wenn die Adresse in einem veröffentlichten Cloud-Bereich liegt.

Begründungscodes

Jeder Wert, den reasons[] tragen kann, und was er bedeutet. Neue Codes kommen nur hinzu.

• account_many_devices — eines Ihrer Konten wurde innerhalb von 24 Stunden auf drei oder mehr Geräten geprüft (wenn Sie accountId senden; nur zur Information)
• account_new_device — ein bereits geprüftes Konto auf einem Gerät, das es noch nie benutzt hat (wenn Sie accountId senden; nur zur Information)
• anonymous_network — ein anonymisierendes Netz ohne benannten Betreiber
• antidetect_browser — ein Fake-Browser (Antidetect-Tooling oder eine manipulierte Umgebung)
• antidetect_profile_burst — fünf oder mehr neue Browser auf einem Gerätetyp innerhalb eines Tages, jeder mit eigenem Canvas-Fingerprint: die Fake-Browser-Profile eines Geräts (Browser-Konsistenz-Beta; nur review)
• antidetect_randomization — ein Konto zeigt auf demselben Gerätetyp zwei Canvas-Fingerprints aus zwei Browsern: ein randomisierender Fake-Browser (Browser-Konsistenz-Beta mit Konto-ID; nur review)
• automation_detected — ein Script oder Headless-Browser
• datacenter_asn — eine Rechenzentrums- oder Cloud-Adresse
• device_many_accounts — drei oder mehr Ihrer Konten auf einem Gerät innerhalb von 24 Stunden (wenn Sie accountId senden; aus Erlauben wird Prüfen, nie Blockieren)
• disposable_email — eine Wegwerf-E-Mail-Adresse
• emulator_detected — ein Emulator
• gpu_inconsistent — der WebGL-Bericht des Browsers widerspricht sich selbst und nennt eine GPU, die er nicht haben kann (Browser-Konsistenz-Beta; nur review)
• high_activity_device — ein ungewöhnlich oft gesehenes Gerät (weiches Signal)
• ip_blocklisted — eine Adresse auf einer Blockliste
• ip_many_accounts — drei oder mehr Ihrer Konten von einer Adresse innerhalb von 24 Stunden; geteilte Ausgänge wie VPNs und Mobilfunkanbieter zählen nie (wenn Sie accountId senden; nur zur Information)
• multi_account_device — ein Gerät, das bereits hinter mehreren Ihrer Konten steckt
• privacy_relay — Apples iCloud Private Relay, anstelle von proxy_detected (allein: review)
• private_browsing — ein Inkognito- oder privates Fenster
• proxy_detected — ein Residential- oder Cloud-Proxy
• timezone_mismatch — die Zeitzone des Browsers widerspricht der Adresse (nur wenn geprüft)
• tor_exit_node — ein Tor-Exit
• virtual_machine — ein Browser in einer virtuellen Maschine (allein: review)
• vpn_detected — ein VPN-Dienst (network.service nennt ihn, wenn bekannt)

Test-Token

Senden Sie eines davon als token mit Ihrem Live-Schlüssel, Ihrem Testschlüssel oder sk_test_sandbox. Mit Ihren eigenen Schlüsseln befolgen sie Ihre Regeln und Ausnahme-Pins (test_vpn ist damit ein Einzeiler, um eine Regel zu prüfen); sie werden nie berechnet. Aus der Konsole gemachte Aufrufe werden als Testzeilen gespeichert, damit unter Ereignisse etwas zu sehen ist.

IP-Lookup

Ein Urteil für eine bloße IP-Adresse — kein Browser-Token nötig. Gleicher Schlüssel und gleiches Stundenlimit wie /v1/evaluate; Lookups haben ein eigenes Monatskontingent, das 10-Fache der Besucherprüfungen des Tarifs (100.000 im Monat im kostenlosen Tarif).

curl https://maskbreak.com/v1/lookup/185.220.101.34 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "ip": "185.220.101.34",
  "known": true,
  "verdict": "block",            // allow | review | block
  "risk_score": 90,
  "signals": { "vpn": false, "proxied": false, "tor": true, "dch": false, "anon": true },
  "network": { "asn": 60729, "org": "Tor exit node", "country": null, "city": null,
               "registration_country": "DE", "source": "asn_table" },
  "latency_ms": 12
}

Verbrauch

Der Kontingentstand Ihres Schlüssels als Endpunkt — fragen Sie ihn ab, statt Ratenlimit-Header aus Ihrer letzten Antwort auszulesen.

curl https://maskbreak.com/v1/usage \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

{
  "key_type": "live",            // or "test"
  "plan": "free",                // free | starter | growth | scale | custom | public_interest
  "monthly_limit": 10000,
  "month_used": 2481,
  "monthly_lookup_limit": 100000,
  "month_lookups_used": 5210,
  "month_resets_at": "2026-08-01T00:00:00.000Z",  // 00:00 UTC on the 1st of next month
  "grandfathered_until": null,   // set while an account created before 1 Oct 2026 keeps its previous allowance
  "hourly_limit": 1000,
  "used_this_hour": 412,
  "remaining": 588,
  "resets_at": "2026-07-19T11:00:00.000Z",  // end of the rolling 60 minutes that began with your first call; null if nothing used yet
  "total_evaluations": 183204,
  "limit_hits": 3
}

Limits und Hinweise. Das Stundenfenster beginnt mit Ihrem ersten Aufruf; das Monatskontingent folgt dem Kalendermonat (UTC). Nutzungswarnungen werden dem Inhaber bei 80 % und beim Erreichen des Stundenlimits gesendet, für einen Live-Schlüssel höchstens einmal je Schwelle innerhalb von 24 Stunden, sowie bei etwa 80 % und 100 % des Monatskontingents. Der Testschlüssel löst keine Stundenwarnungen aus; seine Prüfungen zählen zum Monatskontingent und können daher die Monatswarnungen auslösen. /v1/usage verbraucht kein Auswertungskontingent, ist aber auf 120 Lesezugriffe pro Minute und Adresse begrenzt, auch für Konten im öffentlichen Interesse (429 mit Retry-After). Der Endpunkt setzt die IP-Allowlist des Schlüssels nicht durch; eine Kontosperrung führt weiterhin zu 403. Wiederholte ungültige Zugangsdaten können eine 15-minütige Adresssperre auslösen (429, Retry-After: 900).

Webhooks

Bedrohungsalarme an Slack, Discord oder Ihren eigenen Endpunkt — konfiguriert im Integration-Tab der Konsole unter Alarme.

const crypto = require('crypto');
const express = require('express');
const app = express();

// Raw body required — verify the exact bytes Maskbreak signed,
// never a re-serialized JSON.parse() of them.
app.post('/webhooks/sentinel', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.SENTINEL_WEBHOOK_SECRET;  // shown next to the URL in the dashboard
  const ts  = req.get('X-Maskbreak-Timestamp') || '';
  const sig = req.get('X-Maskbreak-Signature') || '';

  // Freshness: reject anything older than 5 minutes (replay defense)
  const age = Math.abs(Date.now() / 1000 - Number(ts));
  if (!ts || !Number.isFinite(age) || age > 300) return res.status(400).end();

  // "sha256=" + HMAC_SHA256(secret, timestamp + "." + rawBody), hex digest
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(ts + '.').update(req.body).digest('hex');

  // Constant-time compare — never ===
  const a = Buffer.from(sig), b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body);  // { event: "threat.detected", event_id, ip, threat_type, details }
  // ... handle it (queue it, alert, block the IP upstream)
  res.status(200).end();  // answer 2xx fast — deliveries time out after 10 s
});

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

app = Flask(__name__)
SECRET = os.environ["SENTINEL_WEBHOOK_SECRET"].encode()  # shown next to the URL in the dashboard

@app.post("/webhooks/sentinel")
def sentinel_webhook():
    ts  = request.headers.get("X-Maskbreak-Timestamp", "")
    sig = request.headers.get("X-Maskbreak-Signature", "")

    # Freshness: reject anything older than 5 minutes (replay defense)
    try:
        fresh = abs(time.time() - int(ts)) <= 300
    except ValueError:
        fresh = False
    if not fresh:
        abort(400)

    # "sha256=" + HMAC_SHA256(secret, timestamp + "." + raw_body), hex digest.
    # Sign request.get_data() — the exact raw bytes, not request.json.
    expected = "sha256=" + hmac.new(
        SECRET, ts.encode() + b"." + request.get_data(), hashlib.sha256
    ).hexdigest()

    # Constant-time compare — never ==
    if not hmac.compare_digest(sig, expected):
        abort(401)

    event = request.get_json(force=True)  # {"event": "threat.detected", "event_id": ..., "ip": ..., "details": ...}
    # ... handle it (queue it, alert, block the IP upstream)
    return "", 200

{
  "event": "threat.detected",
  "event_id": "9f2ce7a4c1d84b7fa3d2c05e8b6f4a19",  // unique per event; same on retries
  "timestamp": "2026-07-19T09:14:03.512Z",
  "ip": "185.220.101.34",
  "threat_type": "Tor",              // or "Custom rule (…)" / "Customer exception (…)"
  "details": {
    "ip": "185.220.101.34", "cc": "DE",
    "vpn": false, "proxied": false, "tor": true, "dch": false,
    "bot": false, "tampering": false, "antidetect": false,
    "virtual_machine": false,        // since 29 Sep 2026; tampering = tampered browser or emulator
    "privacy_relay": false,          // since 10 Oct 2026; true = Apple's iCloud Private Relay (review), proxied stays true
    "decision": "block",
    "rule_matched": null,            // signals, when your rule caused the block
    "exception_matched": null        // pins, when your exception caused it
  }
}

MCP für KI-Agenten

Ein gehosteter Model-Context-Protocol-Server — richten Sie einen KI-Agenten darauf, und er kann IPs mit echten Maskbreak-Urteilen prüfen.

{
  "mcpServers": {
    "sentinel": {
      "type": "http",
      "url": "https://maskbreak.com/mcp",
      "headers": { "Authorization": "Bearer sk_live_YOUR_API_KEY" }
    }
  }
}

API-Stabilität & Versionierung

Worauf Sie bauen können, ohne sich zu sorgen, dass sich der Boden bewegt.