Proxy detection API vs IP lookup: what your signup flow needs

Your signup form is about to create an account and grant trial credits. You have the visitor’s IP address, so an IP lookup seems like the obvious check. But the question you need answered is broader: what evidence does this visit provide, and what should happen before the account receives something valuable?

A proxy detection API and an IP lookup can contribute different evidence. Choose the integration by the decision your signup flow needs to make. In particular, do not treat a response containing a vpn field as proof that the endpoint checked for a live VPN tunnel.

Choose the evidence your signup needs

Maskbreak’s current production bare-IP lookup checks Tor exits and cloud-server ranges. Live VPN and proxy detection uses an SDK token through POST /v1/evaluate; the service is named when known. The IP lookup reference and evaluation reference describe the separate interfaces.

A lookup is useful when investigating an address from an existing event or screening a server-originated action with no browser collection. It cannot reconstruct a browser visit from an address in yesterday’s log. If the policy depends on browser evidence, collect it at the relevant interaction and handle collection failures explicitly.

Avoid making the IP your entire signup gate

OWASP’s credential stuffing guidance explains that distributed proxy traffic can evade per-IP controls and recommends layered defenses. That guidance addresses authentication attacks; applying its layering principle to signup is a design choice for your application.

Consider two attempts from one workplace connection. One person signs up normally; another repeatedly claims an introductory offer. An address classification alone does not describe those actions. Keep your account and offer rules alongside the network check: verify the contact address, enforce eligibility on the server, and limit repeated attempts against the resource being claimed. Select controls around your actual abuse case.

Collect in the browser, evaluate on the server

After installing the SDK, call window.Sentinel.collect() at submission and forward its token and fingerprintEventId to your own signup backend. Your backend authenticates the evaluation. Secret account API keys stay server-only; neither the HTML nor the browser’s network requests should contain them. See token collection and authentication.

This is the HTTP request shape from your server, with placeholders rather than working credentials. The device event field is optional; include it when collected, and decide whether your policy needs that evidence.

POST /v1/evaluate HTTP/1.1
Host: maskbreak.com
Authorization: Bearer YOUR_SERVER_SIDE_API_KEY
Content-Type: application/json

{
  "token": "BROWSER_COLLECTED_TOKEN",
  "fingerprintEventId": "COLLECTED_DEVICE_EVENT_ID"
}

Send evidence to the API and make the business decision on your server. Never accept a browser-supplied decision: "allow" as authorization. Reject fixture tokens in a production signup integration, and ensure test, sandbox, or sample responses cannot release real benefits. Repeated submissions should resolve to one signup operation, not repeated credit grants.

Read the right response fields

The two endpoints do not share a verdict parser. Evaluation uses decision and network.proxy; lookup uses verdict and signals.proxied. Preserve these distinctions when adapting responses into your own application model. Avoid fallback expressions that substitute allow when an expected field is missing.

A lookup can return known: false, signals: null, and verdict: "allow". Record that as no available IP evidence, not a verified clean connection. Likewise, a service name of null does not clear a live visit; use the classification and decision instead of requiring a recognizable operator name. Consult the evaluation response fields when defining your parser.

Give review a real signup path

In the evaluation engine, a VPN alone leads to review, never block. Proxy or Tor evidence can produce block. Account rules and exceptions can change the final decision, so preserve decision-source details when present. Do not convert every VPN flag or legacy isSuspicious value directly into a refusal.

For a trial product, a possible review path is to verify the email address before releasing credits. Another product may need a restricted account or a staffed queue. These are application policies, not automatic API actions. Write down what releases the restriction, how long it lasts, and what the applicant sees if verification cannot finish.

Keep missing evidence visible

An HTTP error, timeout, invalid JSON, or unexpected decision leaves your application without a usable verdict. A returned degraded: true marks unavailable network evidence and can coexist with a restrictive decision from other signals. Preserve that evidence; an allow with degradation does not establish a clean visit. Missing device data also needs attention if your policy requires it.

Choose the fallback before granting credits. You might hold the grant while allowing account creation, provided the product supports that state. Keep the API outcome and your actual action separately in logs, without raw browser tokens or secret keys. The fraud API timeout guide covers deadlines and incomplete checks.

Validate the whole signup journey

Use the deterministic public sandbox to check response handling, then test actual browser collection separately. Sandbox success is not evidence of real detection. Exercise a normal signup, VPN review, proxy block, unavailable collector, duplicate submission, and recovery from a hold. Observe proposed actions before enforcing them, following the fraud detection rollout guide, and inspect whether each outcome leads to the intended customer journey.