CAPTCHA Widget

A drop-in proof-of-work CAPTCHA delivered as a custom element. No external iframes, no user puzzles — verification runs invisibly in the browser.

Prerequisites

• The tracking script must be loaded on the page.
• Your site must have at least one CAPTCHA config (created automatically with each new site).

Basic usage

Place the custom element anywhere inside a form:

<form method="post" action="/submit">
    <input name="email" type="email" required>
    <sokol-captcha></sokol-captcha>
    <button type="submit">Send</button>
</form>

The widget auto-discovers your Site ID from the tracking script, fetches a challenge from /api/v1/sentinel/challenge, solves the ALTCHA v3 PoW v2 challenge, and injects a hidden altcha input into the form on submit.

For invisible auth flows, use:

<sokol-captcha name="altcha" display="invisible" page-type="login"></sokol-captcha>

Submit buttons stay enabled. On submit, Sokol temporarily disables the submitter, completes the invisible verification, then resumes the original form submission.

Verifying server-side

On your backend, POST the submitted token plus the user-supplied fields to /api/v1/sentinel/verify with the CAPTCHA server secret in the X-Sokol-Server-Secret header. Never put this secret in browser code or a URL. The public API key used to request a challenge is intentionally rejected by the verification endpoint:

POST /api/v1/sentinel/verify
Content-Type: application/json
X-Sokol-Server-Secret: YOUR_SERVER_SECRET

{
    "payload": "<value of altcha from the form>",
    "fields": { "email": "user@example.com" }
}

The response contains:

• verified — boolean PoW result.
• powVersion, algorithm, expired, invalidSignature, invalidSolution, and verificationMs — technical verification details.
• score — risk score from 0 (clean) to 100 (very likely abuse).
• reason — comma-separated list of triggered indicators (e.g. VPN/Proxy Detected).
• verificationData + signature — the signed verdict you can store as audit evidence.

Modes

You can toggle modes from the site's Security tab in the console.

Sokol Edge challenge pages

The Sokol Edge enforcement page uses the same tracking bundle and <sokol-captcha> component, but supplies the local plugin challenge endpoint through challenge-url. This same-origin override prevents browser challenge creation from calling the central backend synchronously while retaining Sokol intelligence collection:

<script
    data-sokol-site="YOUR_SITE_ID"
    src="https://sokol-static.my-k.cloud/v1/sokol.iife.js"
    defer></script>
<sokol-captcha
    name="sokol"
    challenge-url="/.sokol/challenge?..."
    gate-submit="false"></sokol-captcha>

challenge-url is restricted to the current origin. The Edge Agent still chooses the proof-of-work profile from its synchronized policy and local risk context.