VPN detection API testing: cases for allow, review and block

A useful VPN detection API test proves what your application does with the answer. A green check beside a JSON response does not show that the signup form offers a review path, that a blocked attempt receives no credits, or that a timeout stays separate from an approved visitor.

Build three kinds of checks: deterministic fixtures for parsing and branching, application tests for customer outcomes, and controlled live visits for browser collection. Keep their results separate. If you are looking for a VPN test data API, start with fixtures, but do not present their predictable answers as evidence of detection quality.

Start with the supported sandbox fixtures

The Maskbreak public sandbox accepts POST /v1/evaluate with Authorization: Bearer sk_test_sandbox and a supported test_* token. It returns deterministic simulated evidence, marked test: true and sandbox: true. It does not detect a real connection.

Send only the token for your baseline tests. Additional email or timezone inputs can add signals and change the outcome. The following expectations apply to those token-only public sandbox requests.

The cloud-server fixture is a useful trap for accidental policy changes: evaluation does not block it merely for hosting classification. A production bare-IP cloud-range lookup instead returns review before exceptions. Keep endpoint expectations separate; do not copy a score threshold between them.

Run a small contract check

Run this as a Node.js module with built-in Fetch support. The key below is deliberately public. Your account’s secret API keys still belong only on your server. The deadline is a test-runner setting, not a performance claim or a recommended signup budget.

import assert from 'node:assert/strict';

const cases = [
  ['test_clean', 'allow', null, null],
  ['test_vpn', 'review', 'vpn', 'vpn_detected'],
  ['test_proxy', 'block', 'proxy', 'proxy_detected'],
  ['test_datacenter', 'allow', 'datacenter', 'datacenter_asn'],
  ['test_tor', 'block', 'tor', 'tor_exit_node'],
];

for (const [token, decision, flag, reason] of cases) {
  const response = await fetch('https://maskbreak.com/v1/evaluate', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_test_sandbox',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ token }),
    signal: AbortSignal.timeout(5000),
  });
  assert.equal(response.status, 200, `${token}: HTTP failure`);
  const data = await response.json();
  assert.equal(data.test, true);
  assert.equal(data.sandbox, true);
  assert.equal(data.decision, decision, token);
  assert.ok(Array.isArray(data.reasons));
  if (flag) assert.equal(data.network[flag], true);
  if (reason) assert.ok(data.reasons.includes(reason));
  if (token === 'test_clean') {
    for (const key of ['vpn', 'proxy', 'tor']) {
      assert.equal(data.network[key], false);
    }
  }
}
console.log('Five sandbox cases passed; live detection was not tested.');

MDN’s Fetch guide explains that HTTP error responses do not automatically reject the promise. Check status before parsing and let failed assertions fail the run. Avoid a catch handler that prints success after a network error. Assert required fields and relevant reasons without requiring the entire response to remain byte-for-byte identical.

Assert the customer outcome after the verdict

The script checks the API contract. Your application tests must go further:

• Allow: normal validation still runs, and repeated submissions grant a trial benefit once.
• Review: the applicant sees the intended verification or restricted-account path. A VPN alone means review, never an automatic engine block.
• Block: the protected operation does not execute, including through a background job or an alternative signup route.

Do not route on isSuspicious alone: the VPN fixture sets that legacy flag while returning review. Test your decision mapping directly. Test the absence of a known service name too; production can name a VPN or proxy service when known, but your handler must work without one. See the response reference.

Test missing evidence as its own condition

Add local mocks for connection failure, deadline expiry, HTTP 401, HTTP 429, malformed JSON, and an unexpected decision. These are integration failures, not verdicts about the visitor. Include an HTTP 200 response carrying allow and degraded: true; it must not become “all checks passed.” Also test degraded review and block so available restrictive evidence is preserved.

For authenticated live evaluation, an absent token can produce a degraded response, whereas a rejected token produces an error. Neither establishes a clean visitor. Test missing device evidence when your policy requires it, and simulate a late response after your application has already chosen a fallback. The timeout guide explains how to keep those states distinct.

Separate account policy from public fixtures

The public sandbox bypasses account rules and exceptions. Use account credentials in staging to test those settings; they can change the final decision for a fixture. Record the policy configuration and inspect decision_source and engine_decision when returned. A fixture test with an IP exception is different from a visitor exception needing real device context.

An account test key with a real browser token exercises the live pipeline with test semantics; it is different from the public sandbox. See account test keys. Keep fixture runners isolated from production signup handlers. Reject test tokens and simulated response markers before granting real account privileges.

Finish with controlled live visits

Use your own test accounts and connections: a normal visit, a VPN connection, an authorized proxy setup, and a browser where collection is unavailable. Collect fresh SDK tokens and verify that your backend receives them. Current production raw-IP lookup only checks Tor and cloud ranges; it cannot substitute for live VPN or proxy testing. See lookup limitations.

Record the intended setup separately from the observed signals and customer outcome; investigate disagreements instead of relabeling the test. OWASP recommends layered defenses, including plans for individual controls failing. Keep your other signup safeguards active, then use the rollout guide to observe proposed decisions and verify recovery before broader enforcement.