IPScanner

Integrations

Form gate

A token from the visitor's browser, checked by your server with the site's secret.

Issue a token

POST/v1/gate/token
No key needed1 request per uncached visitor

Parameters

  • sitekeystringRequired

    The form gate's site key, from the dashboard.

  • signalsobjectRequired

    Browser tells from gate.js: headless_flags, user_agent and client.

Response fields

  • tokenstring

    Single-use token for the form. Expires after five minutes.

  • expiresAtstring

    When the token expires, ISO 8601.

  • errorstring

    On failure: 403 hostname_mismatch (the page's Origin is not one of the gate's hostnames), 404 unknown_site, 429 rate_limit_exceeded or quota_exhausted. gate.js then sends the form without a token.

curl -X POST https://ipscanner.io/v1/gate/token \
  -H "Origin: https://shop.example.com" \
  -H "Content-Type: application/json" \
  -d '{
    "sitekey": "site_4fQ8nZ2kLm7xR1vT9cBw",
    "signals": {
      "headless_flags": {
        "webdriver": false,
        "headless_ua": false
      },
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 Safari/605.1.15"
    }
  }'
Response
{
  "token": "Z3RfNGZROG5aMmtMbTd4UjF2VDljQnd8MTc2MDAwMDAwMHxrM3Z4.Qm9yZGVyIGNvbGxpZQ",
  "expiresAt": "2026-10-09T09:35:00Z"
}

Verify a token

POST/v1/gate/verify
Site secretNot metered

Parameters

  • secretstringRequired

    The form gate's secret. Server-side only, never in a page.

  • tokenstringRequired

    The ipscanner-token value the form sent.

  • remote_ipstring

    The visitor's IP as your server sees it. Optional; sets ip_match.

Response fields

  • successboolean

    True when the token is valid and unused.

  • classstring

    verified_bot, malicious_automation, ai_agent, tor, vpn, proxy, relay, hosting or human.

  • actionstring

    Your policy's action for the class: allow, flag or block.

  • modestring

    monitor or enforce. In monitor mode a block is yours to act on.

  • confidencenumber

    Confidence from 0 to 1.

  • networkobject

    classification, anonymized, provider and vpn_provider. provider and vpn_provider are Starter and above; null on Free.

  • network.vpn_providerstring | null

    VPN service on a vpn address (NordVPN, Mullvad...), when known. Starter and above; null on Free.

  • signalsstring[]

    The automation tells that fired, such as webdriver. Empty for a clean visitor.

  • hostnamestring

    The page hostname the token was issued for.

  • issued_atstring

    When the token was issued, ISO 8601.

  • ip_matchboolean

    False when remote_ip was sent and differs from the address the token was issued to.

  • lockedstring[]

    Dotted paths of the fields sent as null on this plan. Absent on Starter and above.

  • planRequiredstring

    Plan that includes the locked fields. Absent on Starter and above.

  • errorstring

    With success false: 400 missing_token, invalid_token, expired_token, already_used or hostname_mismatch; 401 invalid_secret.

curl -X POST https://ipscanner.io/v1/gate/verify \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "gs_YOUR_GATE_SECRET",
    "token": "Z3RfNGZROG5aMmtMbTd4UjF2VDljQnd8MTc2MDAwMDAwMHxrM3Z4.Qm9yZGVyIGNvbGxpZQ",
    "remote_ip": "203.0.113.7"
  }'
Response
{
  "success": true,
  "class": "human",
  "action": "allow",
  "mode": "enforce",
  "confidence": 0.6,
  "network": {
    "classification": "residential_clean",
    "anonymized": false,
    "provider": null,
    "vpn_provider": null
  },
  "signals": [],
  "hostname": "shop.example.com",
  "issued_at": "2026-10-09T09:30:00Z",
  "ip_match": true
}