API Reference

From zero to working integration in 5 minutes. Create a free key at /signup — 1,000 requests/hour, no card.

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

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 Key; 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 each key answers /v1/usage with its own hourly allowance.

Every account has a personal sk_test_… key. It runs the live pipeline and records test events, without increasing live usage or sending live webhooks; it has its own hourly allowance and 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 and /v1/lookup, 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 and keeps working through a key rotation (it resolves to whatever your current key is), so rotating does not revoke tokens already issued — stop issuing new ones and let the old ones expire. 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 every page where you want to evaluate users. One script loads both detection layers — network intelligence (VPN, proxy, datacenter) and device intelligence (antidetect browsers, bots, tampering) — and injects both tokens into your forms.

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

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 and returns { token, fingerprintEventId }. Forward both to your backend. (Or read the monocle and sentinel_fp hidden inputs directly.)

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

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 billed, 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, zero footprint): every account also has a personal sk_test_… key (Settings → API Key), 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, excluded from usage and stats, never fire webhooks or limit emails, and the response carries "test": true. 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.

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

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

How the decision is made

The engine returns block for a proxy, Tor exit, detected bot, emulator or browser tampering. A VPN alone 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.

• anonymous_network — an anonymising network with no operator named
• antidetect_browser — a fake browser (antidetect tooling or a tampered environment)
• automation_detected — a script or headless browser
• datacenter_asn — a datacenter or cloud address
• disposable_email — a throwaway email address
• emulator_detected — an emulator
• high_activity_device — a device seen unusually often (soft signal)
• ip_blocklisted — an address on a blocklist
• multi_account_device — a device already behind several of your accounts
• 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 virtual machine
• 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, same hourly bucket as /v1/evaluate.

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": 205100, "org": "F3 Netze", "country": "DE", "city": null },
  "latency_ms": 121
}

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"
  "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. Usage warnings are sent to the owner at 80% and at the cap, at most once per threshold per 24 hours for a live key. Test keys do not send these warnings. /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,
    "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.