API teatmik

Kolm sammu esimese täieliku kontrollini: lisa skript vormiga lehele, saada kontroll oma serverist ja saada oma vorm üks kord. Loo tasuta võti aadressil /signup — tasuta paketis 10 000 külastajakontrolli kuus, ilma kaardita.

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

Enne otsuse jõustamist

Testi eraldi tavapäraseid otsuseid, puuduvat teavet ja kliendi võimalusi pärast takistust jätkata. Need juhendid käsitlevad rakendusepoolseid valikuid, mida API vastus sinu eest teha ei saa.

• Kavanda ajalõpu korral kasutatav varulahendus
• Plaani turvaline kasutuselevõtt

Kutsu liivakasti otspunkti ühe klõpsuga. Ilma registreerumiseta, ilma API-võtmeta — ainult päris /v1/evaluate vastuse kujud, mida saad oma koodi kopeerida.

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

{
  "klõpsa ▶ Käivita päring": "et näha reaalajas JSON-vastust"
}

Tootmispäringud kasutavad POST /v1/evaluate koos SDK-lt saadud token-iga ja päisega Authorization: Bearer sk_live_.... Näidisotspunkt tagastab sama vastuse kuju, nii et saad oma parsimisloogika enne registreerumist valmis ehitada.

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

{
  "klõpsa ▶ Käivita otsing": "et saada selle IP kohta reaalajas otsus"
}

Kuidas see töötab

Maskbreak kasutab kolmeastmelist voogu klient → sinu taustsüsteem → Maskbreaki API, et su salajane võti ei jõuaks kunagi brauserisse.

Autentimine

Kõik päringud otspunktile /v1/evaluate peavad sisaldama sinu salajast API-võtit Bearer-tokenina. Oma võtme leiad töölaualt.

Võtme vahetamine

Vaheta võtit konsoolist (Integratsioon → Vaheta või Seaded → API võtmed; parooli küsitakse uuesti). Uus võti töötab kohe ja eelmine võti töötab veel 24 tundi, nii et juurutus saab üle minna ilma pausita. Kui võti on lekkinud, lõpetab Seadetes Tühista vana võti kohe selle armuaja otsekohe. Armuaja jooksul arvestatakse mõlema võtme päringud samast tunnilimiidist ja /v1/usage näitab mõlemale samu numbreid.

Igal kontol on isiklik sk_test_… võti. See käivitab reaalajas kontrolliahela ja salvestab testsündmused, kuid ei saada pärisliikluse veebihaagi teavitusi; selle kontrollid lähevad sinu kuulimiidi sisse, sellel on oma tunnilimiit ning sellele ei rakendata IP-lubamisnimekirja. Avalik sk_test_sandbox võti vastab ainult deterministlikele testtokenitele, ilma kontota ja sündmusi salvestamata. Tootmisvõtme IP-lubamisnimekiri piirab /v1/evaluate ja /v1/lookup kasutamist ning tokeni väljastamist otspunktilt /oauth/token (muult aadressilt 400 unauthorized_client), kuid mitte /v1/usage kasutamist.

OAuth 2.0 Client Credentials Uus

Vaheta oma konto e-post ja API-võti lühiajalise bearer-tokeni vastu standardse client_credentials grandiga. Token kannab sinu konto ID-d, mitte kunagi võtit ennast. See kehtib 60 minutit, autendib sinu parasjagu kehtiva sama tüüpi võtmena ning on seotud võtmega, millega see vermiti: pärast vahetamist töötab see edasi seni, kuni see võti kehtib (eelmise võtme 24-tunnine armuaeg); eelmise võtme tühistamine, teine vahetus või testvõtme vahetamine lõpetab selle kohe vastusega 401 — siis vermi uus. Sinu sk_test_ võtmega vermitud token jääb testtunnuseks. API-võtmed töötavad täpselt nagu varem; see on lisandus.

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

Kasuta tagastatud access_token-i Authorization: Bearer päises kõikjal, kus API-võtit aktsepteeritakse. Tokenid aeguvad; uuenda vahetust korrates. Võti ise ei lahku kunagi sinu serverist.

Lisa Maskbreaki SDK vormiga lehele. Üks skript laadib mõlemad tuvastuskihid — võrguanalüüs (VPN, proksi, andmekeskus) ja seadmeanalüüs (antidetect-brauserid, botid, võltsimine) — ning lisab mõlemad igasse vormi, millel on class="monocle-enriched" (vormil endal, mitte kunagi sisestusväljal).

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

Sinu sait saadab Content-Security-Policy päise? helmeti vaikepoliitika teeb seda ja blokeerib skripti, kuni lisad oma direktiividele SDK enda hostid: 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 ja worker-src https://mesu.maskbreak.com blob:. Osa, mille poliitika blokeerib, jääb tühjaks ja kontroll jätkub ilma selleta. Integratsioonijuhendis on helmeti seadistus.

SDK laadimine ja tokenite genereerimine võtab ~1–2 sekundit. Kui seadmekiht ei saa töötada (nt karastatud brauser blokeerib selle), jätkub hindamine ainult võrgukihil.

Vormi saatmisel kutsu Sentinel.collect() — see ootab, kuni seadmekiht on paigas (kõige rohkem 5 sekundit; collect({ timeout: ms }) muudab seda), ja tagastab { token, fingerprintEventId, tz }, juba API nimedega. Edasta need oma taustsüsteemi. Kontrolli enne, et window.Sentinel on olemas, ja ära kunagi hoia vormi kinni, kui skript puudub või on blokeeritud. (Tavaliselt saadetud vormis on selle asemel peidetud väljad monocle, sentinel_fp ja sentinel_tz: sinu server saadab need nimedega token, fingerprintEventId ja tz.) Kliendipoolselt renderdatud rakendus (React, Next.js, Vue)? Midagi lisada pole vaja: skript hoiab ise ühte peidetud vormi, nii et token on olemas ka vormidele, mille sinu rakendus renderdab pärast lehe laadimist.

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

Kutsu seda oma taustsüsteemi serverist — mitte kunagi brauserist. Edasta kliendilt saadud token ja oma salajane API-võti.

Päringu keha

Testimine ilma brauserita: saada deterministlik testtoken — test_clean, test_vpn, test_proxy, test_datacenter või test_tor —, et oma allow / review / block käsitlust otsast otsani proovida. Testpäringud autenditakse ja piiratakse sagedusega nagu päris omad, aga neid ei arvestata, salvestata ega saadeta veebihaakidesse, ja vastus kannab "test": true.

CI & staging ilma kontota: avalik liivakastivõti sk_test_sandbox aktsepteerib samu test_* tokeneid ja tagastab samad deterministlikud kujud — ilma registreerumiseta, midagi ei arvestata, midagi ei salvestata, päris kvooti ei puudutata kunagi. See vastab ainult testtokenitele (reaalliiklus vajab ikka sinu päris võtit) ja on IP kohta piiratud sagedusega. curl -X POST https://maskbreak.com/v1/evaluate -H "Authorization: Bearer sk_test_sandbox" -H "Content-Type: application/json" -d '{"token":"test_vpn"}'

Sinu enda testvõti (täiskonveier): igal kontol on ka isiklik sk_test_… võti (Seaded → API võtmed), mis erinevalt liivakastist jooksutab kogu reaalajakonveierit — päris tokenid, päris seadmeanalüüs, sinu reeglid ja erandikinnitused kaasa arvatud. Selle loodud sündmused on konsoolis märgitud testina, statistikast välja jäetud, ei käivita kunagi veebihaake, ja vastus kannab "test": true. Selle kontrollid lähevad nagu konsooli enda kontrollidki sinu kuu mahu hulka; ülal toodud fikseeritud testtokenid mitte. Sellel on oma tunnilimiit ja see on sihilikult IP-lubamisnimekirjast vabastatud, et CI ja sülearvutid saaksid konveierit proovida ilma su tootmispiirangusse auke löömata.

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

Saada värske päris brauserisündmus /v1/evaluate aadressile tootmisvõtmega. device.customer_history loendab ainult sinu kliendikonto viimase 90 päeva erinevaid kinnitatud sündmusi ning näitab esimest ja viimast külastust, korduvkülastuse olekut ja seotud kontode arvu. Töölaua Sündmused → Uuri kuvab 50 viimati nähtud seadet. Ajalugu koguneb pärast funktsiooni kasutuselevõttu; vanu sündmusi ei lisata tagantjärele. Sama sündmuse korduv saatmine läheb arvesse ühe korrana. Puuduv seadmetõend tähendab puuduvat ajalugu, mitte uut ega ohutut seadet.

Kontode seostamiseks peab sinu server määrama accountId enda autenditud kasutaja või seansi põhjal, mitte kopeerima brauseri väidetud kontotunnust. Kasuta pseudonüümset ID-d, mitte e-posti aadressi. Ühist seadet kasutavad kontod on taustainfo, mitte pettuse tõend. Testvõtme liiklust sellesse ajalukku ei lisata. Varasemad times_seen, returning ja first_seen väljad säilitavad jagatud loenduri tähenduse; oma külastajate jaoks kasuta customer_history välja.

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

Vastuseobjekt

Õnnestunud päring tagastab 200 OK koos selle JSON-struktuuriga.

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

Kuidas otsus sünnib

Mootor tagastab proksi, Tori väljundi, tuvastatud boti, emulaatori või brauseri manipuleerimise korral block. VPN üksi, virtuaalmasinas töötav brauser või Apple'i iCloud Private Relay üksi (ainus proksi, mis saadetakse ülevaatusele, mitte ei blokeerita) annab tulemuseks review. Muud signaalid ja sinu reeglistik võivad lõppvastust mõjutada. Pilveserveri või anonüümse võrgu lipp üksi ei põhjusta kindlat blokeeringut. Sinu reeglid ja erandid võivad otsuse üle kirjutada; engine_decision lisatakse siis, kui ülekirjutus otsust muudab, mitte igale vastusele.

Piiratud teabega vastused. Võrguteabe puudumisel tagastatakse degraded: true, ip: "unknown" ja võrgulipud väärtusega false. Need false-väärtused tähendavad, et teave pole kättesaadav, mitte seda, et ühendus on puhas. Seadme- või e-posti signaalid, reeglid ja erandid võivad endiselt anda tulemuseks review või block. Hindamiste koguarvust ja sündmuste logist jäetakse välja ainult lihtne mittekahtlane allow-varuvastus; sisuliste otsuste puhul kehtib tavapärane sündmuste ja kasutusarvestuse käsitlus. Autenditud katsed kasutavad endiselt tunnist päringulimiiti.

Lisalipud. test: true igal testtokeni või testvõtme vastusel, sandbox: true, kui kasutati avalikku sk_test_sandbox võtit, sample: true otspunktil /v1/evaluate/sample. /v1/lookup kannab lisaks täiendavat network.cloud objekti, mis nimetab teenusepakkuja, kui aadress asub avaldatud pilvevahemikus.

Põhjusekoodid

Iga väärtus, mida reasons[] kanda võib, ja mida see tähendab. Uusi koode ainult lisatakse.

• account_many_devices — üht sinu kontot kontrolliti 24 tunni jooksul kolmes või enamas seadmes (kui saadad accountId; ainult teadmiseks)
• account_new_device — varem kontrollitud konto seadmes, mida see pole kunagi kasutanud (kui saadad accountId; ainult teadmiseks)
• anonymous_network — anonüümiv võrk ilma nimetatud operaatorita
• antidetect_browser — võltsbrauser (antidetect-tööriist või võltsitud keskkond)
• antidetect_profile_burst — viis või enam uut brauserit ühel seadmetüübil ööpäeva jooksul, igaühel oma lõuendi sõrmejälg: ühe masina võltsbrauseri profiilid (brauseri järjepidevuse beeta; ainult review)
• antidetect_randomization — üks konto näitab samal seadmetüübil kahe brauseri kahte lõuendi sõrmejälge: juhuslikustav võltsbrauser (brauseri järjepidevuse beeta koos kontotunnusega; ainult review)
• automation_detected — skript või liideseta (headless) brauser
• datacenter_asn — andmekeskuse või pilve aadress
• device_many_accounts — kolm või rohkem sinu kontot ühes seadmes 24 tunni jooksul (kui saadad accountId; lubamisest saab ülevaatus, mitte kunagi blokeerimine)
• disposable_email — ühekordne e-posti aadress
• emulator_detected — emulaator
• gpu_inconsistent — brauseri enda WebGL-aruanne on vastuoluline ja nimetab GPU, mida tal olla ei saa (brauseri järjepidevuse beeta; ainult review)
• high_activity_device — ebatavaliselt sageli nähtud seade (pehme signaal)
• ip_blocklisted — mustas nimekirjas olev aadress
• ip_many_accounts — kolm või rohkem sinu kontot ühelt aadressilt 24 tunni jooksul; jagatud väljapääsud nagu VPN-id ja mobiilioperaatorid ei loe kunagi (kui saadad accountId; ainult teadmiseks)
• multi_account_device — seade, mis on juba mitme sinu konto taga
• privacy_relay — Apple'i iCloud Private Relay, proxy_detected asemel (üksi: review)
• private_browsing — inkognito- või privaataken
• proxy_detected — residentne või pilveproksi
• timezone_mismatch — brauseri ajavöönd ei klapi aadressiga (ainult kontrollimisel)
• tor_exit_node — Tori väljundsõlm
• virtual_machine — virtuaalmasinas töötav brauser (üksi: review)
• vpn_detected — VPN-teenus (network.service nimetab selle, kui teada)

Testtokenid

Saada üks neist token-ina oma tootmisvõtme, testvõtme või sk_test_sandbox-iga. Sinu enda võtmetega järgivad need sinu reegleid ja erandikinnitusi (nii on test_vpn üherealine viis reegli kontrollimiseks); neid ei arvestata kunagi. Konsoolist tehtud päringud salvestatakse testridadena, et sündmuste logil oleks midagi näidata.

IP-otsing

Otsus paljale IP-aadressile — brauseri tokenit pole vaja. Sama võti ja sama tunnilimiit mis /v1/evaluate; päringutel on oma kuulimiit, mis on paketi külastajakontrollide arv korda 10 (tasuta paketis 100 000 kuus).

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
}

Kasutus

Sinu võtme kvoodiseis otspunktina — küsi seda, selle asemel et viimase vastuse päistest limiite kraapida.

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
}

Limiidid ja teavitused. Tunnine arvestusaken algab sinu esimese päringuga; kuulimiit järgib kalendrikuud (UTC). Omanikule saadetakse kasutushoiatus tunnilimiidi 80% juures ja selle täitumisel, tootmisvõtme puhul kõige rohkem üks kord kummagi läve kohta 24 tunni jooksul, ning kuulimiidi umbes 80% ja 100% juures. Testvõti tunnihoiatusi ei saada; selle päringud lähevad kuulimiidi sisse ja võivad seega käivitada kuulimiidi hoiatused. /v1/usage ei tarbi hindamiskvooti, kuid on piiratud 120 lugemispäringuga minutis aadressi kohta, sealhulgas avaliku huvi kontodel (429 koos Retry-After-iga). Otspunkt ei rakenda võtme IP-lubamisnimekirja; konto peatamine annab siiski vastuseks 403. Korduvad vigased autentimisandmed võivad põhjustada aadressi 15-minutilise blokeeringu (429, Retry-After: 900).

Veebihaagid

Ohuteavitused Slacki, Discordi või sinu enda otspunkti — seadistatakse konsooli Integratsiooni vahekaardil Teavituste all.

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 AI-agentidele

Hallatud Model Context Protocoli server — suuna AI-agent sellele ja ta saab IP-sid päris Maskbreaki otsustega kontrollida.

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

API stabiilsus & versioonimine

Millele saad ehitada, muretsemata, et pind liigub.