API-Referenz

Von null zur funktionierenden Integration in 5 Minuten. Erstellen Sie einen kostenlosen Schlüssel unter /signup — 10.000 Besucherprüfungen im Monat im kostenlosen Tarif, keine Karte.

// STEP 1 — HTML. Load the collector before your form handler.
<script defer 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, after the SDK loads.
document.getElementById('login-form').addEventListener('submit', async (event) => {
  event.preventDefault();
  const { token, fingerprintEventId, tz } = await window.Sentinel.collect();
  const response = await fetch('/your-login-endpoint', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: event.target.email.value, token, fingerprintEventId, tz
    })
  });
  // Handle response.status and the next step in your existing login UI.
});

// STEP 3 — Node 22 / Express backend.
// express, app and existingLoginHandler belong to your application.
// This check is NOT authentication and never creates a login session.
app.use(express.json({ limit: '16kb' }));
app.post('/your-login-endpoint', async (req, res, next) => {
  try {
    const { token, fingerprintEventId, tz, email } = req.body;
    const response = await fetch('https://maskbreak.com/v1/evaluate', {
      method: 'POST',
      signal: AbortSignal.timeout(2000), // example budget; measure your own
      headers: {
        'Authorization': 'Bearer ' + process.env.MASKBREAK_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ token, fingerprintEventId, tz, email })
    });
    if (!response.ok) throw new Error('Visitor check unavailable');
    const result = await response.json();
    // Production gate: never authorize from a fixture or personal test key.
    // Use a live key in MASKBREAK_API_KEY; test the integration separately.
    if (result.test || result.sandbox || result.sample) {
      throw new Error('Synthetic visitor check');
    }
    if (!['allow', 'review', 'block'].includes(result.decision)) {
      throw new Error('Unexpected verdict');
    }
    if (result.decision === 'block') {
      return res.status(403).json({ error: 'Action refused by policy' });
    }
    if (result.decision === 'review' || result.degraded) {
      // Implement an actual step-up flow; never mint a session here.
      return res.status(409).json({ next: 'step_up' });
    }
    req.fraudCheck = result;
    return next(); // normal credential + authorization checks still run
  } catch {
    // Example temporary hold. Choose a fallback for each business action.
    return res.status(503).json({ error: 'Check unavailable; try again shortly' });
  }
}, 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

{
  "click ▶ Run Request": "to see live JSON"
}

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" }

{
  "click ▶ Run Lookup": "for a live verdict on this 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 jeder Seite ein, auf der Sie Nutzer auswerten wollen. Ein Script lädt beide Erkennungsschichten — Netzwerkintelligenz (VPN, Proxy, Rechenzentrum) und Geräteintelligenz (Antidetect-Browser, Bots, Manipulation) — und fügt beide Token in Ihre Formulare ein.

<!-- Maskbreak SDK — network + device, paste inside <head> -->
<script async src="loading..."></script>

<!-- Add class="monocle-enriched" to any form you want evaluated -->
<form class="monocle-enriched" id="my-form">
  <!-- The SDK injects both automatically: -->
  <input type="hidden" name="monocle"    value="eyJ..." /> // network
  <input type="hidden" name="sentinel_fp" value="a1b2..." /> // device
</form>

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 }. Leiten Sie beides an Ihr Backend weiter. (Oder lesen Sie die versteckten Felder monocle und sentinel_fp direkt aus.) 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
  const { token, fingerprintEventId } = await window.Sentinel.collect();

  if (!token) {
    // Network SDK still loading — ask user to try again
    return showError('Security check loading. Please try again.');
  }

  // Forward both 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,
      token, fingerprintEventId  // ← both layers to your backend
    })
  });
});

Ihre Website sendet eine Content-Security-Policy? Ergänzen Sie Ihre Direktiven um die eigenen Hosts des SDK: 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.

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.

const response = await fetch('https://maskbreak.com/v1/evaluate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    token: req.body.token,   // as sent by your frontend (see Quick Start Step 2)
    fingerprintEventId: req.body.fingerprintEventId,
    tz: req.body.tz
  })
});

const data = await response.json();
// data.decision → 'allow' | 'review' | 'block' (covers VPN, proxy,
// datacenter, Tor, antidetect, automation) — route on this
// data.reasons  → machine-readable why

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

# pip install sentinelsup
from sentinel import Sentinel

s = Sentinel(api_key='sk_live_YOUR_API_KEY')  # or omit — reads SENTINEL_KEY env var

# request_body is the JSON body parsed by your web framework.
# This SDK requires a non-empty token; use raw HTTP for degraded fallback or tz.
result = s.evaluate(
    token=request_body.get('token', ''),
    fingerprint_event_id=request_body.get('fingerprintEventId')
)

# result.decision → 'allow' | 'review' | 'block' — route on this
# result.reasons  → machine-readable why

if result.is_blocked:
    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"}'

// composer require sentinelsup/sdk
$sentinel = new \Sentinel\Client();  // or pass the key — reads SENTINEL_KEY env var

// The frontend sends JSON, not a URL-encoded form.
// This SDK requires a non-empty token; use raw HTTP for degraded fallback or tz.
$input = json_decode(file_get_contents('php://input'), true, 512, JSON_THROW_ON_ERROR);
$result = $sentinel->evaluate([
    'token' => $input['token'] ?? '',
    'fingerprintEventId' => $input['fingerprintEventId'] ?? null,
]);

// $result->decision → 'allow' | 'review' | 'block' — route on this
// $result->reasons  → machine-readable why

if ($result->isBlocked()) {
    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=1 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,
    "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,
    "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 oder ein Browser in einer virtuellen Maschine 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.

• anonymous_network — ein anonymisierendes Netz ohne benannten Betreiber
• antidetect_browser — ein Fake-Browser (Antidetect-Tooling oder eine manipulierte Umgebung)
• automation_detected — ein Script oder Headless-Browser
• datacenter_asn — eine Rechenzentrums- oder Cloud-Adresse
• disposable_email — eine Wegwerf-E-Mail-Adresse
• emulator_detected — ein Emulator
• high_activity_device — ein ungewöhnlich oft gesehenes Gerät (weiches Signal)
• ip_blocklisted — eine Adresse auf einer Blockliste
• multi_account_device — ein Gerät, das bereits hinter mehreren Ihrer Konten steckt
• 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
    "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.