API Reference

Three steps to your first complete check: add the script to the page with your form, send the check from your server, then submit your form once. Create a free key at /signup — 10,000 visitor checks a month on the Free plan, no card.

// 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);

Before you enforce a verdict

Test normal decisions, missing evidence and customer recovery separately. These guides cover the application-side choices that an API response cannot make for you.

• Design your timeout fallback
• Plan a safe rollout

Hit the sandbox endpoint with one click. No signup, no API key — just real /v1/evaluate response shapes you can copy-paste into your code.

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

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

Production calls use POST /v1/evaluate with a token from the SDK and an Authorization: Bearer sk_live_... header. The sample endpoint returns the same response shape so you can wire your parsing logic before signing up.

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

{
  "click ▶ Run Lookup": "for a live verdict on this IP"
}

How It Works

Maskbreak uses a 3-step Client → Your Backend → Maskbreak API flow to keep your secret key off the browser.

Authentication

All requests to /v1/evaluate must include your secret API key as a Bearer token. Find your key in the Dashboard.

Rotating your key

Rotate from the console (Integration → Rotate, or Settings → API keys; your password is asked again). The new key works at once and the previous key keeps working for 24 hours, so a deploy can switch over without a gap. If a key has leaked, Revoke old key now in Settings ends that grace immediately. During the grace both keys count against the same hourly allowance, and /v1/usage reports the same figures for either.

Every account has a personal sk_test_… key. It runs the live pipeline and records test events without sending live webhooks; its checks count toward your monthly allowance, it has its own hourly allowance and it bypasses the IP allowlist. The public sk_test_sandbox key only answers deterministic test tokens, with no account or stored events. A live-key IP allowlist restricts /v1/evaluate, /v1/lookup and minting a token at /oauth/token (400 unauthorized_client from any other address), not /v1/usage.

OAuth 2.0 Client Credentials New

Exchange your account email and API key for a short-lived bearer token at the standard client_credentials grant. The token carries your account id, never the key itself. It lives for 60 minutes, authenticates as your current key of its type, and is bound to the key it was minted with: after a rotation it keeps working while that key does (the previous key's 24-hour grace), and revoking the previous key, a second rotation or rotating the test key ends it at once with a 401, so mint a new token when you get one. A token minted with your sk_test_ key stays a test credential. API keys keep working exactly as before; this is additive.

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_..."}'

Use the returned access_token anywhere an API key is accepted in the Authorization: Bearer header. Tokens expire; refresh by repeating the exchange. The key itself never leaves your server.

Add the Maskbreak SDK to the page with your form. One script loads both detection layers — network intelligence (VPN, proxy, datacenter) and device intelligence (antidetect browsers, bots, tampering) — and injects both into every form that carries class="monocle-enriched" (on the form itself, never on an input).

<!-- 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>

Your site sends a Content-Security-Policy? helmet's default policy does, and it blocks the script until you add the SDK's own hosts to the directives you have: 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 and worker-src https://mesu.maskbreak.com blob:. A part the policy blocks leaves its value empty, and the check goes on without it. The integration guide shows the helmet configuration.

The SDK takes ~1–2 seconds to load and generate the tokens. If the device layer can’t run (e.g. a hardened browser blocks it), evaluation continues on the network layer alone.

On submit, call Sentinel.collect() — it waits for the device layer to settle (at most 5 seconds; collect({ timeout: ms }) changes that) and returns { token, fingerprintEventId, tz }, already under the API's names. Forward them to your backend. Check that window.Sentinel exists first, and never hold the form when the script is missing or blocked. (A plain form post carries the hidden inputs monocle, sentinel_fp and sentinel_tz instead: your server sends them as token, fingerprintEventId and tz.) Client-rendered app (React, Next.js, Vue)? Nothing extra to add: the script keeps one hidden form of its own, so the token is there even for forms your app renders after the page loads.

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
    })
  });
});

Call this from your backend server — never from the browser. Pass the token from the client and your secret API key.

Request Body

Testing without a browser: send a deterministic test token — test_clean, test_vpn, test_proxy, test_datacenter, or test_tor — to exercise your allow / review / block handling end-to-end. Test calls are authenticated and rate-limited like real ones but never counted toward your monthly allowance, stored, or webhooked, and the response carries "test": true.

CI & staging without an account: the public sandbox key sk_test_sandbox accepts the same test_* tokens and returns the same deterministic shapes — no signup, nothing billed, nothing stored, never touches a real quota. It only answers test tokens (live traffic still needs your real key) and is rate-limited per IP. curl -X POST https://maskbreak.com/v1/evaluate -H "Authorization: Bearer sk_test_sandbox" -H "Content-Type: application/json" -d '{"token":"test_vpn"}'

Your own test key (full pipeline): every account also has a personal sk_test_… key (Settings → API keys), and unlike the sandbox it runs the complete live pipeline — real tokens, real device intelligence, your rules and exception pins included. Events it creates are badged as test in the console, left out of your stats, never fire webhooks, and the response carries "test": true. Its checks count toward your monthly allowance, like the console’s own checks; the fixed test tokens above do not. It has its own hourly bucket and is deliberately exempt from the IP allowlist, so CI and laptops can exercise the pipeline without punching holes in your production restriction.

// 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();
}

Send a fresh, real browser event to /v1/evaluate with a live key. device.customer_history counts distinct verified events on your account only, over the last 90 days. It includes first and latest visits, returning status and the number of associated accounts. The dashboard shows the 50 most recently seen devices under Events → Investigate. History starts after this feature is enabled on the service; old events are not backfilled. Repeated event submissions count once. Missing device evidence means no history—not a new or safe device.

For account links, your backend must set accountId from its own authenticated user/session, never copy a claimed account ID from the browser. Use a pseudonymous ID, not an email. Accounts sharing a device are context, not proof of fraud. Test-key traffic is excluded from this new history. Legacy times_seen, returning and first_seen fields keep their existing shared-counter meaning; use customer_history for your own visitors.

// 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.

Response Object

A successful call returns 200 OK with this JSON structure.

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

How the decision is made

The engine returns block for a proxy, Tor exit, detected bot, emulator or browser tampering. A VPN alone, a browser inside a virtual machine, or Apple's iCloud Private Relay alone (the one proxy that is reviewed, not blocked) returns review. Other signals and your policy can affect the final answer. A cloud-server or anonymous-network flag alone is not a hard block. Your rules and exceptions can override the decision; engine_decision is included when an override changes it, not on every response.

Degraded answers. Missing network evidence produces degraded: true, ip: "unknown" and false network flags. Those false flags mean unavailable evidence, not a clean connection. Device or email signals, rules and exceptions can still produce review or block. Only the bare non-suspicious allow fallback is omitted from evaluation totals and Events; meaningful verdicts follow normal event and usage handling. Authenticated attempts still use the hourly request allowance.

Extra flags. test: true on any test-token or test-key answer, sandbox: true when the public sk_test_sandbox key was used, sample: true on /v1/evaluate/sample. /v1/lookup also carries an additive network.cloud object naming the provider when the address sits in a published cloud range.

Reason codes

Every value reasons[] can carry, and what it means. New codes are only ever added.

• account_many_devices — one of your accounts checked on three or more devices within 24 hours (when you send accountId; informational)
• account_new_device — an account you checked before, now on a device it has never used (when you send accountId; informational)
• anonymous_network — an anonymising network with no operator named
• antidetect_browser — a fake browser (antidetect tooling or a tampered environment)
• antidetect_profile_burst — five or more new browsers on one machine type within a day, each with its own canvas fingerprint: one machine’s antidetect profiles (browser-consistency beta; review only)
• antidetect_randomization — one account showing two canvas fingerprints from two browsers on the same machine type: a randomising antidetect browser (browser-consistency beta, sent with an account id; review only)
• automation_detected — a script or headless browser
• datacenter_asn — a datacenter or cloud address
• device_many_accounts — three or more of your accounts on one device within 24 hours (when you send accountId; raises allow to review, never to block)
• disposable_email — a throwaway email address
• emulator_detected — an emulator
• gpu_inconsistent — the browser’s own WebGL report contradicts itself, naming a GPU it cannot have (browser-consistency beta; review only)
• high_activity_device — a device seen unusually often (soft signal)
• ip_blocklisted — an address on a blocklist
• ip_many_accounts — three or more of your accounts from one address within 24 hours; shared exits such as VPNs and mobile carriers never count (when you send accountId; informational)
• multi_account_device — a device already behind several of your accounts
• privacy_relay — Apple's iCloud Private Relay, in place of proxy_detected (review on its own)
• private_browsing — an incognito or private window
• proxy_detected — a residential or cloud proxy
• timezone_mismatch — browser time zone disagrees with the address (only when checked)
• tor_exit_node — a Tor exit
• virtual_machine — a browser inside a virtual machine (review on its own)
• vpn_detected — a VPN service (network.service names it when known)

Test tokens

Send one of these as token with your live key, your test key or sk_test_sandbox. With your own keys they obey your Rules and exception pins (so test_vpn is a one-line way to verify a rule); they are never billed. Calls made from the console are stored as test rows so the Events log has something to show.

IP Lookup

A verdict for a bare IP address — no browser token needed. Same key and hourly cap as /v1/evaluate; lookups have their own monthly allowance, 10× the plan’s visitor checks (100,000 a month on the Free plan).

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
}

Usage

Your key’s quota position as an endpoint — poll it instead of scraping rate-limit headers off your last response.

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 and notices. The hourly window starts with your first call; the monthly allowance follows the calendar month (UTC). Usage warnings are sent to the owner at 80% and at the cap of the hourly window, at most once per threshold per 24 hours for a live key, and at about 80% and 100% of the monthly allowance. The test key sends no hourly warnings; its checks count toward the monthly allowance, so they can trigger the monthly ones. /v1/usage consumes no evaluation quota but is limited to 120 reads/minute per address, including public-interest accounts (429 with Retry-After). The endpoint does not enforce the key's IP allowlist; suspension still returns 403. Repeated invalid credentials can trigger a 15-minute address lockout (429, Retry-After: 900).

Webhooks

Threat alerts pushed to Slack, Discord, or your own endpoint — configured on the console’s Integration tab, under Alerts.

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 for AI Agents

A hosted Model Context Protocol server — point an AI agent at it and it can screen IPs with real Maskbreak verdicts.

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

API Stability & Versioning

What you can build on without worrying about the ground moving.