v1 Laadimine…

API viide

Integreeri nähtamatu boti- & proksituvastus oma tootesse. Ilma CAPTCHA-deta. Ilma hõõrdumiseta. Alla 150 ms serveripoolselt iga hindamise kohta.

Viimati uuendatud augustis 2026 · iga API muudatus jõuab muudatuste logisse · ainult lisavate muudatuste stabiilsuspoliitika

Peata võltsregistreerumised & prooviperioodide kuritarvitamine

Hinda registreerumist enne, kui konto olemas on — üks POST sinu taustsüsteemist.

Taba VPN-i taha peitunud kasutajad

Vaata VPN-i vastuse kuju mänguväljakul näidisandmetega — võtit pole vaja.

Ühenda CI-ga

Deterministlikud testtokenid + avalik sk_test_sandbox võti — kontot pole vaja.

Rünnakupõhised mängukavad: konto ülevõtmine, kaarditestimine, boonuste kuritarvitamine, ja veel →

★

Kiirstart

Nullist töötava integratsioonini 5 minutiga. Loo tasuta võti aadressil /signup — 1000 päringut tunnis, ilma kaardita.

Node.js SDK npm install @sentinelsup/sdk npm ↗ · GitHub ↗

Pythoni SDK pip install sentinelsup PyPI ↗ · GitHub ↗

OpenAPI 3.1 https://maskbreak.com/openapi.json Spetsifikatsioon ↗ ·

Seadista AI abil Claude Code · Cursor · Copilot · Windsurf

Kasutad AI-koodiassistenti? Kleebi see prompt ja ta ühendab Maskbreaki sinu rakendusse otsast otsani — esiotsa skript, taustsüsteemi kontroll, keskkonnamuutuja ja test. Ta järgib masinloetavat juhendit aadressil maskbreak.com/integrate.md.

Fetch https://maskbreak.com/integrate.md and follow it to add Maskbreak fraud protection to this app — protect signup, login, and checkout. My API key is sk_live_YOUR_API_KEY; put it in a SENTINEL_KEY env var, never in client-side code. Then show me how to test it.

Sinu Maskbreaki API otspunkt

Laadimine…

Sinu taustsüsteem kutsub seda URL-i. Sinu API võti autendib päringu.

Täielik integratsiooninäide

// ——— STEP 1: Add SDK to your HTML <head> —————————————————————————————————————
<script async src="loading..."></script>
<form class="monocle-enriched" id="login-form">
  <input type="email" name="email" />
  <!-- SDK auto-injects BOTH: name="monocle" (network) + name="sentinel_fp" (device) -->
</form>

// ——— STEP 2: Read both tokens in your frontend JS ——————————————————————————————
document.getElementById('login-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const email = e.target.email.value;
  // Sentinel.collect() waits for the device layer, then returns both.
  const { token, fingerprintEventId } = await window.Sentinel.collect();
  // Send to YOUR backend (never call Maskbreak directly from the browser)
  await fetch('your-login-endpoint', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, token, fingerprintEventId })
  });
});

// ——— STEP 3: Evaluate on your backend (Node.js) ——————————————————————————————
app.post('/your-login-endpoint', async (req, res) => {
  const { email, token, fingerprintEventId } = req.body;

  const result = await fetch('https://maskbreak.com/v1/evaluate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    // Both layers — network + device — in one call.
    body: JSON.stringify({ token, fingerprintEventId })
  });

  const data = await result.json();

  if (data.decision === 'block') {
    return res.status(403).json({ error: 'Bot or proxy detected.' });
  }
  if (data.decision === 'review') {
    // e.g. require email verification or step-up auth
  }

  // ✓ Connection is clean — proceed
  res.json({ success: true });
});

▶

Proovi otse

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

Päring

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

Autentimist pole vaja · 30 päringut/min · tagastab näidisandmed

Vastus

ootab käivitamist…

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

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.

Otsi päris IP-d

päris konveieri otsus · võtmeta · piiratud sagedusega — mõni katse minutis

Päring

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

IP-aadress

Päris otsus reaalajakonveierist (Tori väljund on ette täidetud). Rangelt piiratud sagedusega — mõni katse minutis; mahu jaoks kasuta võtmega GET /v1/lookup.

Vastus

ootab käivitamist…

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

Kuidas see töötab

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

Kogumine brauseris

Maskbreaki SDK töötab nähtamatult sinu kasutaja brauseris ja kogub telemeetriat. Ta lisab sinu vormidesse krüpteeritud token-i.

Token edastatakse

Sinu esiots saadab tokeni koos ülejäänud vormiandmetega sinu enda taustsüsteemi serverisse.

API hindamine

Sinu taustsüsteem kutsub POST /v1/evaluate sinu salajase võtmega. Maskbreak tagastab kohe ohuluure raporti.

Autentimine

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

Authorization: Bearer sk_live_YOUR_SECRET_KEY

Hoia oma võti salajas

Ära pane sk_live_… kunagi oma HTML-i, JavaScripti ega muusse kliendipoolsesse koodi. Kasuta seda ainult oma taustsüsteemi serverikeskkonnas.

Võtme vahetamine

Vaheta võtit konsoolist (Integratsioon → Vaheta või Seaded → API võti; 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 vastab kumbki võti otspunktile /v1/usage oma tunnilimiidiga.

Iga konto juurde kuulub veel kaks võtit: isiklik sk_test_… võti, mis jooksutab kogu konveierit ilma arvestamata, salvestamata või teavitamata (oma tunnilimiit, IP-lubamisnimekirjast vabastatud), ja avalik sk_test_sandbox võti, mis vastab ainult deterministlikele testtokenitele ilma kontota. Valikuline IP-lubamisnimekiri (Seaded → API võtme turvalisus) piirab reaalajavõtme sinu serveriaadressidega; mujalt tulevad päringud saavad 403 koos süüdlase aadressiga vihjes.

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 ja töötab edasi ka võtme vahetamisel (see lahendub sinu parasjagu kehtivaks võtmeks), nii et vahetamine ei tühista juba väljastatud tokeneid — lõpeta uute väljastamine ja lase vanadel aeguda. Sinu sk_test_ võtmega vermitud token jääb testtunnuseks. API võtmed töötavad täpselt nagu varem; see on lisandus.

OAuthi tokeni otspunkt

POST /oauth/token

Vaheta e-post + API võti bearer-tokeni vastu. Avastusmetaandmed aadressidel /.well-known/oauth-authorization-server ja /.well-known/oauth-protected-resource.

cURL

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 SDK

Lisa Maskbreaki SDK igale lehele, kus tahad kasutajaid hinnata. Üks skript laadib mõlemad tuvastuskihid — võrguluure (VPN, proksi, andmekeskus) ja seadmeluure (antidetect-brauserid, botid, võltsimine) — ning lisab mõlemad tokenid sinu vormidesse.

HTML — kleebi <head> sisse

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

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.

Kogu tokenid

Vormi saatmisel kutsu Sentinel.collect() — see ootab, kuni seadmekiht on paigas, ja tagastab { token, fingerprintEventId }. Edasta mõlemad oma taustsüsteemi. (Või loe otse peidetud välju monocle ja sentinel_fp.)

JavaScript (esiots)

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

Kutsu evaluate-otspunkti

POST laadimine…

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

Päringu keha

token string kohustuslik

Krüpteeritud token kliendi väljalt input[name="monocle"].

fingerprintEventId string

Seadmeluure sündmuse ID — SDK püüab selle ja lisab kui sentinel_fp; edasta see siia (mõlemat nime aktsepteeritakse), et avada device.* signaalid (antidetect, automatiseerimine, emulaator, …). Jäta see ära ja saad ainult võrgupõhise otsuse.

accountId string

Valikuline: sinu enda konto/kasutaja ID selle seansi jaoks. Koos fingerprintEventId-ga loeb Maskbreak, mitme erineva kontoga on see seade sinu API võtme all seotud olnud, ja tagastab device.linked_accounts / device.multi_account — mitmikkontode tuvastus ilma lisaintegratsioonita. Salvestatakse ainult ühesuunalise räsina.

email string

Valikuline: e-posti aadress, millega külastaja registreerub. Lisab vastusesse email.disposable — kontrollitakse pidevalt uuendatava tuhandete ühekordsete domeenide voo vastu. Tabamus lisab põhjuse disposable_email, tõstab risk_score-i ja tõstab allow tasemele review. Aadressi kontrollitakse ajutiselt ning seda ei salvestata ega logita kunagi.

tz string

Valikuline: külastaja IANA ajavöönd, nt Europe/Tallinn. Meie kliendi SDK saadab selle automaatselt kui sentinel_tz, mida see otspunkt samuti aktsepteerib; ise saad selle lugeda käsuga Intl.DateTimeFormat().resolvedOptions().timeZone — ilma loaküsimuse ja geolokatsioonita. Lisab vastusesse timezone ploki. Kui ühendus näib tavaline, aga brauseri kell kuulub teise riiki, on see võrgukihist mööda pääsenud residentse proksi kuju: see lisab põhjuse timezone_mismatch, tõstab risk_score-i ja tõstab allow tasemele review. Sihilikult mitte rakendatud VPN-i, proksi, Tori ega andmekeskuse väljundi puhul — kellaga vastuollu minek ongi see, mida need teevad — ja mitte kunagi üksi piisav block-iks, sest reisijad ja välismaal elavad inimesed satuvad siia õigustatult.

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, jäljeta): igal kontol on ka isiklik sk_test_… võti (Seaded → API võti), mis erinevalt liivakastist jooksutab kogu reaalajakonveierit — päris tokenid, päris seadmeluure, sinu reeglid ja erandikinnitused kaasa arvatud. Selle loodud sündmused on konsoolis märgitud testina, kasutusest ja statistikast välja jäetud, ei käivita kunagi veebihaake ega limiidikirju, ja vastus kannab "test": true. Sellel on oma tunniämber ja see on sihilikult IP-lubamisnimekirjast vabastatud, et CI ja sülearvutid saaksid konveierit proovida ilma su tootmispiirangusse auke löömata.

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

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

result = s.evaluate(token=sentinel_token)  # from the form POST body

# 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": "eyJ..."}'
// composer require sentinelsup/sdk
$sentinel = new \Sentinel\Client();  // or pass the key — reads SENTINEL_KEY env var

$result = $sentinel->evaluate([
    'token' => $_POST['monocle'],  // hidden input the client SDK adds
]);

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

if ($result->isBlocked()) {
    http_response_code(403);
    exit();
}

Vastuseobjekt

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

Väli	Tüüp	Kirjeldus
decision	string	Soovitatav tegevus: `"allow"`, `"review"` või `"block"`. Ainult nõuandev — poliitika määrad sina. `reasons` massiiv selgitab iga otsust, et saaksid selle logida või näidata oma lõppkasutajale keeldumise põhjust. Kui seadistad töölaual oma reeglid, tagastab see väli sobiva signaali puhul sinu tegevuse (rangeim reegel võidab).
engine_decision	string	`decision_source` tagastatakse alati, kui sinu poliitika sellele sündmusele sobis: `"rules"` (koos `rule_matched`-iga, mis loetleb reegli käivitanud signaalid) või `"exception"` (koos `exception_matched`-iga, mis nimetab IP/külastaja kinnituse sinu töölaua erandite loendist — otsesed kinnitused on signaalireeglitest tähtsamad). `engine_decision` ilmub lisaks siis, kui vaste otsust tegelikult muutis, säilitades mootori enda riskiskoori otsuse.
risk_score	integer	Koondriskiskoor 0–100 üle kõigi võrgu- ja seadmesignaalide. Oma reeglid seda ei muuda.
isSuspicious	boolean	Pärandmugavuslipp. `true`, kui VPN, proksi, antidetect, automatiseerimine või emulaator rakendus. Tori ja andmekeskuse signaalid tõstavad `risk_score`-i ja juhivad `decision`-it (Tor blokeerib), kuid ei sea seda lippu — täieliku katvuse jaoks suuna `decision`-i järgi.
ip	string	Kasutaja paljastatud, päris IP-aadress. Peegeldatud väljal `details.ip`.
country	string	ISO 3166-1 riigikood (nt "US", "EE"). Peegeldatud väljal `details.cc`.
network.vpn	boolean	Tuvastatud kommertslik VPN (NordVPN, Proton, ExpressVPN jne). Peegeldatud väljal `details.vpn`.
network.proxy	boolean	Tuvastatud residentne või SOCKS/HTTP proksi. Peegeldatud väljal `details.proxied`.
network.datacenter	boolean	Liiklus teadaoleva andmekeskuse / pilveteenusepakkuja ASN-ist. Peegeldatud väljal `details.dch`.
network.tor	boolean	Tuvastatud Tori väljundsõlm. Peegeldatud väljal `details.tor`.
network.anonymous	boolean	Tuvastatud mis tahes anonüümimiskiht. Peegeldatud väljal `details.anon`.
network.residential	boolean	`true`, kui ei andmekeskuse ega proksi lipp ei rakendunud (näeb välja nagu päris kodu-IP).
network.service	string	Tuvastatud teenusepakkuja, kui teada (nt "PROTON_VPN", "BRIGHT_DATA"). Peegeldatud väljal `details.service`.
device.antidetect	boolean	Antidetect- / sõrmejälge võltsiv brauser (Multilogin, Kameleo, GoLogin jne). Olemas ainult siis, kui `fingerprintEventId` saadeti.
device.automation	boolean	Tuvastatud automatiseeritud brauser (Puppeteer, Playwright, Selenium).
device.emulator	boolean	Mobiiliemulaator.
device.virtual_machine	boolean	Virtuaalmasin.
device.incognito	boolean	Tuvastatud privaatne / inkognitorežiim.
device.privacy_mode	boolean	Täiustatud privaatsusseaded aktiivsed (nt Brave Shields, Firefoxi resist-fingerprinting).
device.ip_blocklisted	boolean	Külastaja IP on e-posti rämpsposti või rünnakuallikate mustades nimekirjades.
device.high_activity	boolean	Seda seadet tuvastatakse ebatavaliselt sageli (kõrge aktiivsusega seade). Informatiivne — sagedased külastused üksi pole pettus, aga koos teiste signaalidega viitavad need sageli automatiseerimisele või farmimisele. Lisab põhjusekoodi `high_activity_device`.
device.visitor_id	string	Püsiv seadme sõrmejälje räsi. Sama seade tagastab sama ID üle seansside ka pärast küpsiste kustutamist — kasulik konto ülevõtmise tõrjeks ja seadmete rühmitamiseks.
device.tampering_score	number	Võltsimisskoor 0–1. Üle 0,6 viitab tugevalt antidetect-brauserile; 0,3–0,6 tähendab pehmeid vastuolusid; alla 0,3 on tavaline.
device.times_seen	integer	Mitu korda Maskbreak on seda seadet viimase 90 päeva jooksul näinud, võtmestatud külastaja-ID ühesuunalise räsiga (toor-ID-d ei salvestata kunagi). `1` tähendab täiesti uut seadet — uued seadmed kõrge väärtusega toimingutel on klassikaline pettuse märk.
device.first_seen	string	ISO 8601 ajatempel, millal Maskbreak seda seadet sinu API võtme all esimest korda nägi. Olemas, kui seade on tuvastatud — väga värske `first_seen` kõrge väärtusega toimingu kõrval on sama pettuse märk mis `times_seen: 1`, vanus lihtsalt selgesõnaliselt välja toodud.
device.returning	boolean	True, kui `times_seen` > 1 — seda seadet on varem hinnatud.
device.linked_accounts	integer	Mitme erineva kontoga on seda seadet sinu API võtme all viimase 90 päeva jooksul nähtud. Olemas ainult siis, kui edastad päringus koos `fingerprintEventId`-ga oma `accountId`. Mõlemad tunnused salvestatakse ainult ühesuunaliste räsidena.
device.multi_account	boolean	True, kui `linked_accounts` > 1 — mitmikkontode põhisignaal (boonuste kuritarvitamine, prooviperioodide farmimine, topeltregistreerumised). Lisab põhjusekoodi `multi_account_device`.
email.disposable	boolean	Olemas ainult siis, kui päring sisaldas valikulist `email` parameetrit. `true`, kui aadress kasutab teadaolevat ühekordset domeeni — lisab põhjuse `disposable_email` ja tõstab `allow` tasemele `review`.
timezone.reported	string	Olemas ainult siis, kui päring sisaldas äratuntavat `tz`-d. Brauseri teatatud IANA vöönd, tagasi peegeldatuna.
timezone.country	string	ISO 3166-1 alpha-2 riik, kuhu see vöönd kuulub.
timezone.matches_ip	boolean	`true`, kui vööndi riik võrdub `country`-ga (väljund-IP oma). Ehita sellele oma reegel, kui tahad meie omast rangemat poliitikat.
timezone.checked	boolean	`false` VPN-i, proksi, Tori või andmekeskuse väljundi puhul, kus lahknevus on ootuspärane ja me midagi ei rakenda. Kui `false`, loe `matches_ip`-d infona, mitte otsusena.
reasons	string[]	Masinloetavad koodid selle kohta, millised signaalid rakendusid (nt `"vpn_detected"`, `"datacenter_asn"`, `"antidetect_browser"`).
evaluated_in_ms	integer	Serveripoolne töötlemisaeg selle päringu jaoks millisekundites.

200 OK — kahtlane ühendus

{
  "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": {  /* legacy mirror */
    "ip": "185.107.80.12",
    "cc": "EE",
    "vpn": true,
    "proxied": false,
    "anon": true,
    "dch": true,
    "service": "PROTON_VPN"
  }
}

200 OK — puhas ühendus

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

Kuidas otsus sünnib

block, kui on olemas kõva signaal: proksi, Tori väljund, bot või automatiseerimine, emulaator või võltsbrauser. review, kui on VPN või võltsitud brauser ilma kõva signaalita. allow muul juhul — andmekeskuse aadress või anonüümiv võrk üksi tõstab ainult risk_score-i. Sinu reeglid võivad iga signaali vastuse üle kirjutada; mootori enda otsus tagastatakse alati kõrval.

Halvendatud vastused. Kui kliendi token API-ni ei jõua või võrgukiht pole kättesaadav, tagastab päring ikkagi 200 koos "ip": "unknown", kõik võrgulipud false ja decision: "allow". Seda ei arvestata ega salvestata. Käsitle seda kui „tõendeid pole“, mitte kui puhast külastajat.

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.

anonymous_network — anonüümiv võrk ilma nimetatud operaatorita
antidetect_browser — võltsbrauser (antidetect-tööriist või võltsitud keskkond)
automation_detected — skript või peata brauser
datacenter_asn — andmekeskuse või pilve aadress
disposable_email — ühekordne e-posti aadress
emulator_detected — emulaator
high_activity_device — ebatavaliselt sageli nähtud seade (pehme signaal)
ip_blocklisted — mustas nimekirjas olev aadress
multi_account_device — seade, mis on juba mitme sinu konto taga
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äljund
virtual_machine — virtuaalmasin
vpn_detected — VPN-teenus (network.service nimetab selle, kui teada)

Testtokenid

Saada üks neist token-ina oma reaalajavõ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.

Token	Teeseldud külastaja	Signaalid	Otsus
`test_clean`	203.0.113.42 · US	mitte midagi	allow
`test_vpn`	198.51.100.18 · NL	VPN, andmekeskus (PROTON_VPN)	review
`test_proxy`	203.0.113.9 · DE	proksi, andmekeskus (BRIGHT_DATA)	block
`test_datacenter`	203.0.113.7 · DE	andmekeskus (AWS)	allow
`test_tor`	203.0.113.99 · null	Tor (TOR)	block

IP-otsing

Otsus paljale IP-aadressile — brauseri tokenit pole vaja. Sama võti, sama tunniämber mis /v1/evaluate.

GET /v1/lookup/{ip} — serveripoolseks sõelumiseks seal, kus klienti ei jookse: lubamisnimekirja kontrollid, hulgiskoorimine, oma logide rikastamine. Ainult võrgusignaalid (pole seadet, mille sõrmejälge võtta), nii et kasuta /v1/evaluate-i alati, kui brauser on mängus. Palja IP puhul rakenduvad Tori väljundi ja pilvevahemike kontrollid; VPN-i ja proksi tunnelid — ja teenuse nimi väljal network.service — tuvastatakse reaalsel külastusel /v1/evaluate kaudu, nii et signals.vpn ja signals.proxied tulevad siin tagasi väärtusega false.

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
}

known: false tähendab, et ühelgi luureallikal polnud arvamust — otsus on siis allow koos risk_score: 0-ga, mis on „midagi ei leitud“, mitte puhtuse garantii. Töölaual seadistatud erandikinnitused kehtivad ka siin (verdict_source: "exception" koos täiendavalt säilitatud engine_verdict-iga). Signaalide kirjapildid (proxied, dch) on külmutatud — turvaline parsida.

Päringulimiidid

Maskbreak on avatud beetas — kogu ligipääs on tasuta. Paralleelselt kehtib kaks limiiti; kumb iganes enne täis saab, tagastab 429.

Ulatus	Limiit
API võtme kohta (tasuta)	1000 päringut / tunnis
API võtme kohta (avalik huvi)	Ilma tunnilimiidita
Allika IP kohta	50 000 päringut / tunnis (heakskiidetud avaliku huvi võtmed pääsevad sellest läbi)

Beeta ajal kuulimiiti pole. IP-põhine lagi on kaitse ühe masina ohjeldamatu kuritarvituse vastu. Retry-After on igas 429 vastuses kaasas.

Võtmega /v1/evaluate ja /v1/lookup vastused kannavad ka päiseid X-RateLimit-Limit, X-RateLimit-Remaining ja X-RateLimit-Reset (Unixi sekundid), et saaksid enne 429-t tagasi tõmmata — ning päist X-Request-Id, mida saad toele tsiteerida, kui midagi tundub valesti.

Avaliku huvi programmi võtmetel (haiglad, rahvatervis, riigiasutused, valimised, hädaabiteenistused, ülikoolid, registreeritud mittetulundusühingud) tunnilimiiti pole: kolm X-RateLimit-* päist jäetakse ära, mitte ei täideta asendusväärtusega, ja /v1/usage teatab hourly_limit: null koos uncapped: true.

Töökindlus & fail-open käitumine

Maskbreak tõrgub avatuks: kui ülesvoolu võrgu- või seadmeluure pakkuja pole kättesaadav, tagastab hindamine vea asemel oma parimad saadaolevad signaalid ja puuduv pakkuja tähendab, et just need signaalid lihtsalt puuduvad (mitte kunagi valet „puhas“ garantiid). Nii jätkub sinu kassa või sisselogimine pakkuja tõrke ajal kõigi blokeerimise asemel. Seepärast käsitle decision-it nõuandvana ja sea oma läved — kõrge panusega toimingute puhul eelista "review" korral astmelist kontrolli kõva lubamisele, et halvendatud hindamine ei laseks ohtu vaikselt läbi. Kui see juhtub, kannab vastus tipptasemel degraded: true; kui otsus on paljas puhas vaikeväärtus, ei arvestata päringut total_evaluations hulka (sinu kasutus /v1/usage ja töölaual) ega kirjutata sinu sündmuste logisse — kuigi nagu iga autenditud päring kasutab see ikkagi ühe päringu tunnilimiidist, nii et X-RateLimit-Remaining liigub. Puuduvat või tühja tokenit käsitletakse samamoodi. Token, mille pakkuja tagasi lükkab (vigane või võltsitud), pole pakkuja tõrge: see tagastab 400 Invalid token. ja seda samuti ei arvestata.

Veakoodid

Kõik API veavastused sisaldavad error stringivälja. Üks erand, märgitud 403 all: blokeering servas tagastab lihtteksti, mitte JSON-i.

400 Bad Request — vigane token (pakkuja lükkas tagasi või pole string). Puuduv või tühi token pole viga: sellele vastatakse fail-open põhimõttel koos degraded: true.
401 Unauthorized — vigane või puuduv API võti.
403 Forbidden — konto peatatud (võta ühendust support@maskbreak.com) või päringu tegija IP pole sinu võtme IP-lubamisnimekirjas (Seaded → API võtme turvalisus; väli hint nimetab päringu teinud aadressi). Samalt aadressilt uuesti proovida ei saa.

Kolmas põhjus, ja see segadust tekitav: paljas error code: 1010 kui text/plain ilma JSON-kehata ei tule meilt — see on meie serv, mis lükkab tagasi sinu HTTP-kliendi vaikimisi User-Agenti. Python-urllib on levinud juhtum. Sea mis tahes päris User-Agent päis ja see kaob; iga ametlik SDK teeb seda juba.
429 Rate Limited — tunnine päringulimiit ületatud (1000/h võtme kohta, 50 000/h allika IP kohta). Heakskiidetud avaliku huvi võtme puhul ei tagastata kunagi.
500 Server Error — ootamatu sisemine viga. Turvaline uuesti proovida koos taganemisega.

Kasutus

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

GET /v1/usage — autendi API võtme endaga (Authorization: Bearer …). Töötab mõlema võtmetüübiga — sk_live_ ja sk_test_ teatavad kumbki oma tunniämbri, nimetatud väljal key_type — ja päring on tasuta: see ei tarbi kunagi kvooti, nii et seda pollivad monitorid ei saa sinu limiiti ära süüa.

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
}

used_this_hour ja remaining on nõuandvad: loendurid on mälus ja protsessipõhised, nii et need lähtestuvad juurutamisel — käsitle neid reaalajanäidikuna, mitte auditikirjena (tegeliku limiidi jõustamist see ei mõjuta). total_evaluations ja limit_hits on püsivad kontosummad.

Limiidid ja teavitused. Tunnilimiit on jooksev 60-minutiline aken, mis algab sinu esimese päringuga. Kui reaalajavõti jõuab 80%-ni sellest ja uuesti, kui see jõuab laeni, saab konto omanik ühe e-kirja 24 tunni jooksul; testvõti ei saada kunagi kirju. /v1/usage on tasuta kutsuda, aga sellel on oma lagi 120 päringut minutis aadressi kohta (429 koos Retry-After-iga) ja see vastab 403, kui võtme IP-lubamisnimekiri päringu tegija välistab. Korduvad päringud vigase võtmega lukustavad aadressi 15 minutiks (429, Retry-After: 900).

Veebihaagid

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

Millal need käivituvad. Mootori tuvastatud ohtude puhul (VPN, proksi, Tor, andmekeskus koos võltsimisega, botid, antidetect-brauserid) ja iga hindamise puhul, mille sinu enda reeglid otsustasid block-ida. Slacki ja Discordi URL-id saavad kanalisse valmis sõnumi; iga muu HTTPS-otspunkt saab JSON-sündmuse (event: "threat.detected" koos IP, ohutüübi ja signaalide üksikasjadega). Töölaua nupp Saada test toimetab sama kuju koos event: "test" — kui su vastuvõtja hargneb rangelt sündmuse tüübi järgi, käsitle mõlemat, muidu näeb testnupp välja nagu vaikne tõrge.

Ehtsuse kontroll. Iga tarne on allkirjastatud sinu konto allkirjasaladusega (näha töölaual veebihaagi URL-i kõrval). Arvuta HMAC_SHA256(secret, timestamp + "." + rawBody), kasutades päist X-Maskbreak-Timestamp, ja võrdle seda (konstantse ajaga) heksdigestiga päises X-Maskbreak-Signature (pärast prefiksit sha256=). Lükka tagasi kõik allkirjastamata, mittevastav või üle 5 minuti vana.

Kopeeritavad vastuvõtjad. Kaks klassikalist viga on kontrollida uuesti serialiseeritud parsitud keha, mitte toorbaitide vastu, ja võrrelda ==-ga. Need vastuvõtjad teevad seda õigesti:

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

Tarne & kordused. Iga sündmust proovitakse kuni 3 korda: ebaõnnestunud tarnet korratakse umbes 1 minuti ja seejärel umbes 8 minuti pärast. Kordused on parima pingutuse põhimõttel ja protsessisisesed — korduse keskel toimuv juurutus jätab ülejäänud katsed ära —, seega käsitle töölaua sündmuste logi tõe allikana ja veebihaaki parima pingutuse tõukena. 25 viimast tarnet (sündmus, tulemus, viga) on kirjas töölaua Tööriistade sahtlis, säilitatakse 30 päeva; päise kiip näitab hetkeseisu ja kui 5 järjestikust tarnet ebaõnnestub, saadame sulle e-kirja — surnud veebihaaki ei tohi kunagi lugeda kui „ohte pole“. Tarned aeguvad 10 s pärast ega järgi kunagi ümbersuunamisi.

Dubleerimise vältimine event_id järgi. Iga kasulik koormus kannab event_id-d — 32 heksmärki, unikaalne iga sündmuse kohta, olemas ka testsündmustel — ja iga tarne kannab seda ka päises X-Maskbreak-Event-Id. Korduvad tarned kasutavad sama event_id-d, nii et võtmesta oma töötlus selle järgi ja iga sündmust käsitletakse täpselt üks kord, ükskõik mitu katset sinuni jõuab.

Üldise otspunkti kasulik koormus. Mida su vastuvõtja tegelikult saab (Slacki/Discordi URL-id saavad selle asemel vormindatud sõnumi):

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

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

Otspunkt: POST https://maskbreak.com/mcp (voogedastatav HTTP, olekuta). Tööriistad: lookup_ip — sama otsus mis GET /v1/lookup — ja service_status. Autendi kas klassikalise API võtmega Authorization: Bearer sk_live_… või OAuthi access_token-iga otspunktilt POST /oauth/token. Anonüümne kasutus jagab tasuta tööriista rangeid IP-põhiseid limiite; autenditud päringud jooksevad sinu 1000/h kvoodil (sinu IP-lubamisnimekiri kehtib ka siin).

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

Versioonimine. API on versioonitud tees (/v1/). Ühe peaversiooni sees teeme ainult lisavaid muudatusi: uued vastuseväljad, uued valikulised päringuparameetrid, uued signaalipõhjused. Sinu integratsioon peab taluma tundmatuid välju vastustes — see on ainus edasiühilduvuse nõue, mille sulle seame.

Katkestavad muudatused. Vastuseväljade ümbernimetamine või eemaldamine, tüüpide või tähenduse muutmine või otspunkti sulgemine toimub ainult uues peaversioonis (/v2/). Kui see päev tuleb, töötab /v1/ edasi vähemalt 12 kuud pärast teatamist.

Aegumisteade. Igast aegumisest teatatakse vähemalt 90 päeva ette muudatuste logis ja e-kirjaga mõjutatud API võtmetele, koos dokumenteeritud migratsiooniteega. Suurkliendilepingud võivad kinnitada pikemad toeaknad — support@maskbreak.com.

Valmis päris liiklusel käivitama?

Tasuta võti alla minutiga — 1000 päringut tunnis, ilma kaardita.

Alusta tasuta Proovi otse

KKK

Korduma kippuvad küsimused

Kuidas Maskbreaki API-s autentida?

Edasta oma API võti Bearer-tokenina Authorization päises: Authorization: Bearer YOUR_API_KEY. API võtmed genereeritakse pärast registreerumist töölaual, üks konto kohta.

Kui kiire on API vastus?

Serveri otsustusaeg on mediaanina alla 150 ms. Cloudflare'i servavõrk on API ees ja tokenita esimese ringi otsus antakse otse servas.

Milliseid keeli ja SDK-sid toetatakse?

Ametlikud SDK-d on olemas Node.js-ile (@sentinelsup/sdk), Pythonile (sentinelsup) ja PHP-le (sentinelsup/sdk Packagistis), lisaks hallatud MCP-server AI-agentidele. REST API-t saab otse kutsuda igast HTTP-võimelisest keskkonnast, sealhulgas Go, PHP, Ruby, Java, Rust, C#, Kotlin ja Swift.

Mida tasuta aste sisaldab?

1000 API päringut tunnis ilma krediitkaardita. Iga otspunkt on tasuta astmes saadaval — VPN-i tuvastus, residentse proksi skoorimine, antidetect-brauseri tuvastus ja boti sõrmejälg.

Mis juhtub, kui ületan oma päringulimiidi?

API tagastab HTTP 429 koos Retry-After päisega, mis ütleb, millal tunniaken lähtestub. Limiit on 1000 päringut tunnis võtme kohta; tasulist astet, mis seda tõstaks, ei ole. Avaliku huvi organisatsioonid (haiglad, rahvatervis, riigiasutused, valimised, hädaabiteenistused, ülikoolid, registreeritud mittetulundusühingud) saavad avaliku huvi programmi lehel taotleda limiidi eemaldamist.