集成
表单 Gate
来自访客浏览器的令牌,由您的服务器使用站点 Secret 校验。
签发令牌
参数
- sitekeystring必填
表单 Gate 的站点 Key,可在控制台中找到。
- signalsobject必填
gate.js 收集的浏览器特征:headless_flags、user_agent 和 client。
响应字段
- tokenstring
表单使用的一次性令牌,五分钟后过期。
- expiresAtstring
令牌过期时间,ISO 8601 格式。
- errorstring
失败时:403 hostname_mismatch(页面的 Origin 不在该 Gate 的主机名中)、404 unknown_site、429 rate_limit_exceeded 或 quota_exhausted。此时 gate.js 会在没有令牌的情况下提交表单。
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"
}
}'{
"token": "Z3RfNGZROG5aMmtMbTd4UjF2VDljQnd8MTc2MDAwMDAwMHxrM3Z4.Qm9yZGVyIGNvbGxpZQ",
"expiresAt": "2026-10-09T09:35:00Z"
}校验令牌
参数
- secretstring必填
表单 Gate 的 Secret。仅用于服务器端,切勿放入页面。
- tokenstring必填
表单提交的 ipscanner-token 值。
- remote_ipstring
您的服务器看到的访客 IP。可选,用于判断 ip_match。
响应字段
- successboolean
令牌有效且未使用时为 true。
- classstring
verified_bot、malicious_automation、ai_agent、tor、vpn、proxy、relay、hosting 或 human。
- actionstring
您的策略对该类别的动作:allow、flag 或 block。
- modestring
monitor 或 enforce。monitor 模式下由您决定如何处理 block。
- confidencenumber
置信度,范围 0 到 1。
- networkobject
classification、anonymized、provider 和 vpn_provider。provider 和 vpn_provider 仅 Starter 及以上方案提供,Free 方案为 null。
- network.vpn_providerstring | null
vpn 地址所属的 VPN 服务(NordVPN、Mullvad 等),已知时返回。Starter 及以上方案提供,Free 方案为 null。
- signalsstring[]
触发的自动化特征,例如 webdriver。正常访客为空。
- hostnamestring
签发令牌时所在页面的主机名。
- issued_atstring
令牌签发时间,ISO 8601 格式。
- ip_matchboolean
传入 remote_ip 且与签发令牌时的地址不同时为 false。
- lockedstring[]
在当前方案下以 null 返回的字段路径(以点分隔)。Starter 及以上方案不返回此字段。
- planRequiredstring
包含被锁定字段的方案。Starter 及以上方案不返回此字段。
- errorstring
success 为 false 时:400 missing_token、invalid_token、expired_token、already_used 或 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"
}'{
"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
}