整合
表單 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
}