Server-side validation

The endpoint#

POST https://shield.edge.network/siteverify
Content-Type: application/x-www-form-urlencoded

secret=es_secret_...&response=<token>

Both application/x-www-form-urlencoded and application/json bodies are accepted.

Responses#

Success:

{
  "success": true,
  "score": 92,
  "challenge_ts": "2026-07-21T08:00:00.000Z",
  "hostname": "example.com",
  "error-codes": []
}

Failure:

{
  "success": false,
  "error-codes": ["timeout-or-duplicate"]
}

Error codes#

Verified agent tokens#

When automation cryptographically declares its identity (via Web Bot Auth or a confirmed crawler check) and your widget’s agent policy allows it, the token carries the verified identity. The score stays an honest humanity estimate, which is low because it’s automation. Use the agent field to route:

{
  "success": true,
  "score": 8,
  "agent": { "domain": "agent.bot.goog", "verified": true, "method": "web-bot-auth" },
  "challenge_ts": "2026-07-21T08:00:00.000Z",
  "hostname": "example.com",
  "error-codes": []
}

Check agent.verified before trusting a low score: a verified agent is declared automation you may want to serve, while a low score with no agent field is automation that refused to identify itself.

Shadow (report-only) mode#

A widget can be switched to shadow mode in the dashboard (Shield → widget → Settings). In shadow mode siteverify never returns success: false, so nothing is ever blocked. Instead, the response carries what strict enforcement would have decided:

{
  "success": true,
  "shadow": {
    "enabled": true,
    "enforced": false,
    "would_succeed": false,
    "error-codes": ["invalid-input-response"]
  },
  "error-codes": []
}

Log shadow.would_succeed and shadow["error-codes"] during the trial; would-fail and would-escalate counts also accumulate in your widget’s analytics. When the numbers look right, switch shadow mode off. No code changes are needed, since a correct integration already checks success.

Testing your integration#

Fixed test secrets (es_secret_test_pass, es_secret_test_fail, es_secret_test_spent) return deterministic responses so your test suite can exercise every branch without real keys. See Testing & CI.

Using the humanity score#

The score expresses confidence: 1 is confirmed automation, 100 is a confirmed human. “Not human” doesn’t have to mean “not welcome”. A legitimate AI agent acting for a customer will score low, and you may prefer to route it to your API rather than block it.

const { success, score } = await siteverify(token)

if (!success) reject()          // invalid, expired, or replayed token
else if (score >= 70) allow()   // confident human
else if (score >= 40) stepUp()  // uncertain: e.g. require email confirmation
else routeOrBlock()             // automation: block, or redirect to your API

The thresholds are yours to tune. As reference points: in managed mode, background attempts scoring below 40 are automatically escalated to an interactive confirmation before a token is issued, so tokens arriving at your server from managed widgets already had a floor applied.

The score you receive is also the freshest available: the widget verifies at page load, then re-mints its token with a behaviour-informed score once the visitor has actually typed or moved the pointer. By the time the form is submitted, the token usually reflects real interaction as well as the load-time environment. Human motor noise raises the score; machine-perfect input lowers it.