Documentation
Everything you need to put WAU Captcha in front of a form or an API.
How it works
A captcha check takes three calls. Your page fetches a challenge with the public site key, the person answers it and gets a one-time token, and your server redeems the token with the secret key before accepting the request.
Your keys
- Site key (pk_…) — public. Used in the browser to fetch challenges.
- Secret key (sk_…) — private. Used by your server to redeem tokens. Never ship it to a browser.
- Create a key pair on the API keys page of the dashboard.
Quick start
- Create an API key in the dashboard and copy its site key and secret key.
- Add the widget, or <WauCaptcha /> in React, to your form. Once solved, the form sends a hidden field named wau-captcha-token.
- On your server, redeem that token with the secret key and reject the request when it fails.
Browser widget
The widget shows the challenge, a text box and two buttons (for slide_puzzle, a slider instead of the text box and Verify; for animal_jump, the two rounds and a Replay button; for object_rotate, the two rounds with Rotate left, Rotate right and Done, which the arrow keys and Enter work too; for auto_check, a compact box that checks the visitor in the background, with a challenge of its fallback type in its place only when the check is unsure), and loads a new challenge after a wrong answer. With the script build, any element with data-wau-captcha renders by itself.
<script src="https://cdn.jsdelivr.net/npm/@waucaptcha-sdk/client@1.7.0/dist/wau-captcha.global.js" integrity="sha384-6HEd83rCb1Wox8RT7prjB5GeuWB7ylmSj1DBZ9+2varqFoa+2OMJKpCYl7xktRTs" crossorigin="anonymous"></script><form action="/signup" method="post"> <input name="email" type="email" required /> <div data-wau-captcha data-site-key="pk_…" data-base-url="https://api.waucaptcha.com"></div> <button type="submit">Sign up</button></form>The snippet loads an exact release, 1.7.0, with its integrity hash: the browser refuses the file if it differs by a byte from the one published, so neither the CDN nor a later release can change what runs on your page. To move to another release, change the version in the URL and compute its hash:
# In a clone of github.com/wau-captcha/wau-sdk-js:node scripts/sri.mjs 1.7.0# Or with curl and openssl:curl -s https://cdn.jsdelivr.net/npm/@waucaptcha-sdk/client@1.7.0/dist/wau-captcha.global.js \ | openssl dgst -sha384 -binary | openssl base64 -AAttributes: data-site-key and data-base-url (required), data-challenge-type (image_distort, motion_noise, slide_puzzle, animal_jump, object_rotate or auto_check), for auto_check data-fallback-type (slide_puzzle by default) and data-appearance (always or interaction-only), data-input-name (default wau-captcha-token) and data-lang (vi for Vietnamese texts).
With a bundler, render it yourself to get callbacks and your own labels:
npm install @waucaptcha-sdk/clientimport { renderWidget } from "@waucaptcha-sdk/client";const widget = renderWidget(document.querySelector("#captcha"), { siteKey: "pk_…", baseUrl: "https://api.waucaptcha.com", onSuccess(token) { // Also in the hidden input "wau-captcha-token" of the surrounding form. }, onError(error) { console.error(error.code, error.message); },});React component
@waucaptcha-sdk/react gives you one component, <WauCaptcha />, for React 18 or later. Put it inside a form: once solved, the form sends the token in the hidden field wau-captcha-token.
npm install @waucaptcha-sdk/reactNext.js App Router
It works straight from a Server Component page; the server action of the form redeems the token with @waucaptcha-sdk/server.
import { WauCaptcha } from "@waucaptcha-sdk/react";import { signUp } from "./actions";export default function SignUpPage() { return ( <form action={signUp}> <input name="email" type="email" required /> <WauCaptcha siteKey="pk_…" baseUrl="https://api.waucaptcha.com" /> <button type="submit">Sign up</button> </form> );}"use server";import { BehaviorVerdict, WauCaptchaServer, hostnameMatches } from "@waucaptcha-sdk/server";export async function signUp(formData: FormData) { const captcha = new WauCaptchaServer({ secretKey: process.env.WAU_SECRET_KEY!, baseUrl: "https://api.waucaptcha.com", }); const result = await captcha.verifyToken(String(formData.get("wau-captcha-token") ?? "")); // hostname is the website the captcha was solved on: it must be one of yours, listed in // WAU_ALLOWED_HOSTNAMES, e.g. shop.example.com,https://www.shop.example.com if (!result.success || !hostnameMatches(result.hostname, process.env.WAU_ALLOWED_HOSTNAMES)) { throw new Error("Please solve the captcha."); } // Sign-up accepts human only: suspicious is a scripted session, and not_measured means the // client sent no behaviour data (an SDK before 1.2.0 or a hand-written call), so it is untrusted. if (result.behavior.verdict !== BehaviorVerdict.HUMAN) throw new Error("Please try again."); // … create the account}Modal mode
WauCaptchaMode.MODAL shows a box like auto_check's: a checkbox with “I'm not a robot” that opens the challenge in a dialog, which closes by itself once the answer is right; the box then shows a check mark and “Verified”. The challenge only loads when the dialog opens. It needs @waucaptcha-sdk/react 1.7.0 or later; before, it was a button. Callbacks such as onSuccess need a Client Component.
"use client";import { ChallengeType, WauCaptcha, WauCaptchaMode } from "@waucaptcha-sdk/react";export function SignUpCaptcha() { return ( <WauCaptcha mode={WauCaptchaMode.MODAL} challengeType={ChallengeType.MOTION_NOISE} siteKey="pk_…" baseUrl="https://api.waucaptcha.com" onSuccess={(token) => console.log("solved", token)} onError={(error) => console.error(error.code)} /> );}Props
To start over, e.g. after the backend has redeemed the token, change the component's key. To match your brand, set --wau-captcha-primary, --wau-captcha-background or --wau-captcha-border on it or on an ancestor.
Custom UI in the browser
Use WauCaptchaClient to build your own interface. Fetch a challenge when it is shown, not ahead of time: from 1.3.0 the client solves its proof of work in the background meanwhile, and sends it and the site key with the answer. Pass what recordBehavior recorded as behavior, or keys that require behaviour data refuse the answer. For slide_puzzle, animal_jump and object_rotate, trackSlide, trackJump and trackRotate record the drag, the clicks and the presses the way the service checks them, and verifySlide, verifyJump and verifyRotate send them. For auto_check, fetch with newChallenge({ challengeType: ChallengeType.AUTO_CHECK, fallbackType }), record with recordBehavior({ root, page: true }), run probeBrowser(), and once workDone(challenge.id) has resolved and at least 1.5 s have passed since the challenge arrived, send the probe with verifyAuto; success false means a challenge of challenge.fallbackType must be solved instead. A challenge can be answered once: after a wrong answer, fetch a new one.
import { ChallengeType, WauCaptchaClient } from "@waucaptcha-sdk/client";const captcha = new WauCaptchaClient({ siteKey: "pk_…", baseUrl: "https://api.waucaptcha.com" });// Fetch it when it is shown, not ahead of time. The client solves its proof of work meanwhile.const challenge = await captcha.newChallenge(); // or { challengeType: ChallengeType.MOTION_NOISE }image.src = challenge.imageUrl;image.width = challenge.width;image.height = challenge.height;// Sends the site key and the proof of work too; pass { behavior } from recordBehavior as well.const result = await captcha.verify(challenge.id, input.value);if (result.success) { // Send result.token to your server with the form.} else { // Wrong answer: the challenge is used up, fetch a new one.}Verify on a Node.js server
Redeem the token with @waucaptcha-sdk/server (Node.js 18 or later), and check result.hostname, the website the challenge was solved on, against your own domains with hostnameMatches, which also reads them written with https:// or a port. A thrown WauCaptchaError means the token could not be checked; treat it as a failure.
npm install @waucaptcha-sdk/serverimport { BehaviorVerdict, ErrorCode, WauCaptchaServer, hostnameMatches } from "@waucaptcha-sdk/server";const wau = new WauCaptchaServer({ secretKey: process.env.WAU_SECRET_KEY, baseUrl: "https://api.waucaptcha.com",});app.post("/signup", async (req, res) => { try { const result = await wau.verifyToken(req.body["wau-captcha-token"]); // hostname is the website the captcha was solved on: it must be one of yours, listed in // WAU_ALLOWED_HOSTNAMES, e.g. shop.example.com,https://www.shop.example.com if (!result.success || !hostnameMatches(result.hostname, process.env.WAU_ALLOWED_HOSTNAMES)) { return res.status(400).send("Please solve the captcha."); } // result.behavior: { verdict, score, reasons }. not_measured means no behaviour data was sent: // untrusted. Decide about suspicious per form; for sign-up, accept human only. if (result.behavior.verdict !== BehaviorVerdict.HUMAN) return res.status(400).send("Please try again."); } catch (error) { if (error.code === ErrorCode.SECRET_KEY_INVALID) console.error("Check WAU_SECRET_KEY"); return res.status(503).send("Captcha check unavailable."); // fail closed } // … create the account});Verify the package
From 1.3.0 on, every release of the three packages is built and published by GitHub Actions with npm provenance: the package page on npmjs.com shows the commit and the workflow it came from. npm audit signatures checks the registry signatures and provenance attestations of what you installed. Releases before 1.3.0 were published by hand and carry no provenance.
npm install @waucaptcha-sdk/servernpm audit signaturesVerify on a Java server
Redeem the token with com.waucaptcha:waucaptcha-sdk (Java 17 or later, no dependencies), and check result.hostname(), the website the challenge was solved on, against your own domains with result.hostnameMatches, which also reads them written with https:// or a port. result.challengeType() is auto_check for a visitor who passed without a puzzle. The client is immutable and safe to share between threads; a WauCaptchaException means the token could not be checked, so treat it as a failure.
<dependency> <groupId>com.waucaptcha</groupId> <artifactId>waucaptcha-sdk</artifactId> <version>1.1.0</version></dependency>implementation("com.waucaptcha:waucaptcha-sdk:1.1.0")import com.waucaptcha.BehaviorVerdict;import com.waucaptcha.ErrorCode;import com.waucaptcha.SiteVerifyResult;import com.waucaptcha.WauCaptchaClient;import com.waucaptcha.WauCaptchaException;// Build it once and share it: it is immutable and safe to use from many threads.WauCaptchaClient wau = WauCaptchaClient.builder() .baseUrl("https://api.waucaptcha.com") .secretKey(System.getenv("WAU_SECRET_KEY")) .build();boolean captchaPassed(String token) { try { SiteVerifyResult result = wau.verifyToken(token); // hostname is the website the captcha was solved on: it must be one of yours, listed in // WAU_ALLOWED_HOSTNAMES, e.g. shop.example.com,https://www.shop.example.com if (!result.hostnameMatches(System.getenv("WAU_ALLOWED_HOSTNAMES"))) return false; // result.behavior(): verdict, score, reasons. NOT_MEASURED means no behaviour data was sent: // untrusted. Decide about SUSPICIOUS per form; for sign-up, accept HUMAN only. return result.behavior().verdict() == BehaviorVerdict.HUMAN; } catch (WauCaptchaException e) { if (ErrorCode.SECRET_KEY_INVALID.equals(e.getCode())) log.error("Check WAU_SECRET_KEY"); return false; // fail closed: the token could not be checked }}The same client fetches and answers challenges of every type but auto_check, whose answer only the browser SDK can give, with the site key, and sends the site key and the proof of work as the browser SDK does. Keys that require behaviour data, the default for new keys, refuse answers sent without a Behavior, so these calls suit tests and desktop apps; on a website, use the JavaScript widget and verify its token in Java.
WauCaptchaClient captcha = WauCaptchaClient.builder() .baseUrl("https://api.waucaptcha.com") .siteKey("pk_…") .build();Challenge challenge = captcha.newChallenge(ChallengeType.OBJECT_ROTATE);// Show frame 0 of challenge.image(), then of challenge.secondImage(): each is a strip of// challenge.frameCount() frames. Record each round's presses, as RotateRound(frame, presses,// doneMs), and how the person behaved. The call sends the site key and the proof of work too.AnswerResult result = captcha.verifyRotate(challenge, List.of(round1, round2), behavior);if (result.success()) { // Send result.token() to your server, which redeems it with verifyToken.}Other languages
There is no SDK for other languages yet, and none is needed: any backend redeems a token with one HTTPS call to /siteverify, the secret key as a bearer token and the token in a JSON body. Treat anything but a 200 reply with success true as a failed check.
curl -X POST "https://api.waucaptcha.com/siteverify" \ -H "Authorization: Bearer $WAU_SECRET_KEY" \ -H "Content-Type: application/json" \ -d "{\"token\": \"$TOKEN\"}"{ "success": true, "challenge_type": "image_distort", "challenge_ts": "2026-09-23T08:15:02Z", "behavior": { "verdict": "human", "score": 1, "reasons": [] }, "hostname": "shop.example.com"}Bind a key to your websites
Add your domains on the key's page. Challenges are then issued only to pages on those websites, an answer must come from the website that fetched its challenge and name the same site key, and /siteverify returns the website as hostname.
On your server, check hostname against your own domains and refuse the token when it is none of them. hostnameMatches (@waucaptcha-sdk/server 1.7.0 or later) and result.hostnameMatches (Java) do it: they take the domains as a list or as one string with commas between them, such as an environment variable, and read https://Shop.example.com/, shop.example.com:443 and shop.example.com as the same; *.example.com stands for the subdomains of example.com:
import { hostnameMatches } from "@waucaptcha-sdk/server";// WAU_ALLOWED_HOSTNAMES=shop.example.com,https://www.shop.example.com,*.shop.example.comconst result = await wau.verifyToken(token);if (!result.success || !hostnameMatches(result.hostname, process.env.WAU_ALLOWED_HOSTNAMES)) { // Unknown token, or solved on another website: refuse the request.}The browser sets Origin, so domain binding stops other websites from using your key in their visitors' browsers. A script outside a browser can send any Origin it likes: bots are caught by the behaviour verdict and the service's own signals, not by the domain list.
What each SDK version sends
Every request older SDKs send still works; what changes is how much the service can check.
An older client keeps working: without a proof of work its verdict is at most suspicious, and one that sends no behaviour data gets not_measured. It is refused only by a key that requires behaviour data, as new keys do: update to 1.3.0, or turn that switch off on the key's page while you do. The Java SDK records no behaviour itself: it sends a Behavior only when you pass one, so its challenge calls suit tests and desktop apps.
REST API
The SDKs call these endpoints; any HTTP client can call them too. Errors come back as JSON {code, reason, message, metadata}.
GET /challenge/new
Issues a challenge. Query: site_key (required), challenge_type (image_distort by default). image is base64; display it at width × height CSS pixels. slide_puzzle adds piece_image, piece_y, piece_width and piece_height; animal_jump adds second_image, round 2, while image is round 1; object_rotate adds second_image too, and frame_count: image and second_image are each a strip of frame_count frames of width × height side by side. For auto_check, the query takes fallback_type, the type the site prefers if the check does not pass; the reply has no image (image and mime_type empty, width and height 0) and adds fallback_type, the type to load if it does not pass, which the service chooses from what the key allows (empty when it allows none). pow_salt and pow_difficulty are the proof of work the SDK solves before it answers; auto_check asks for more of it. For a key with allowed domains, the Origin of the request (or else of its Referer) must be one of them: DOMAIN_NOT_ALLOWED otherwise.
curl "https://api.waucaptcha.com/challenge/new?site_key=pk_…&challenge_type=image_distort"{ "challenge_id": "0f9c…", "challenge_type": "image_distort", "image": "iVBORw0KGgo…", "mime_type": "image/png", "width": 200, "height": 70, "expires_in": 120, "pow_salt": "q2Jq0tbV1Wm9u3hS5bH0pA==", "pow_difficulty": 15}POST /challenge/verify
Checks an answer. success is false after a wrong answer; the challenge is used up either way. The SDKs also send site_key, pow_nonce (the proof of work) and behavior, how the person behaved while the challenge was on screen. An answer to a challenge of another key, or from another website than the one that fetched it, is wrong. A key that requires behaviour data answers 400 BEHAVIOR_REQUIRED to an answer without it. For auto_check, answer is the JSON the SDK writes from its browser checks, {"v": 1, "ua": …, "lang": …, "f": […]}, from SDK 1.7.0 with "c", the clearance the browser keeps, and "m", counts of how its mouse moves were made, both optional; success false means: show a challenge of its fallback_type. The reply never says why. After a right answer to any other type the reply also carries clearance, which the browser SDK keeps for auto_check; your backend never needs it.
curl -X POST "https://api.waucaptcha.com/challenge/verify" \ -H "Content-Type: application/json" \ -d '{"challenge_id": "0f9c…", "answer": "a8Kq2", "site_key": "pk_…", "pow_nonce": "48213", "behavior": { "version": 1, "elapsed_ms": 4210, … }}'{ "success": true, "token": "…", "expires_in": 120, "clearance": "…" }POST /siteverify
Redeems a token, once. Send the secret key as a bearer token and the token in the body, as JSON {"token": "…"} or as the form token=…, so it never lands in access logs; the query form (?token=) still works for SDKs before 1.3.0 but is deprecated. success is false when the token is unknown, expired, already used or issued for another key. behavior is the verdict of the behaviour check: human, suspicious or not_measured, a score from 0 to 1 and the reasons. hostname is the website the challenge was solved on. challenge_type is auto_check for a visitor who passed without a puzzle, with the reason cleared or first_visit in behavior.reasons, and the fallback's type for one who solved the fallback.
curl -X POST "https://api.waucaptcha.com/siteverify" \ -H "Authorization: Bearer $WAU_SECRET_KEY" \ -H "Content-Type: application/json" \ -d "{\"token\": \"$TOKEN\"}"{ "success": true, "challenge_type": "image_distort", "challenge_ts": "2026-09-23T08:15:02Z", "behavior": { "verdict": "human", "score": 1, "reasons": [] }, "hostname": "shop.example.com"}Challenge types
- image_distort — five characters (letters and digits) distorted in a PNG. The default.
- motion_noise — five characters (capital letters and digits, without O, 0, Q, I and 1) hidden in a looping animated GIF of moving dots.
- slide_puzzle — a 300 × 150 JPEG background with a hole, and a PNG piece to drag horizontally into it. The answer is JSON the SDK writes from the drag, which is also checked for human movement, so use the SDK rather than building it by hand. Keyboard-only users cannot solve it: keep image_distort available where accessibility matters.
- animal_jump — two animated GIFs of 300 × 150, one per round, each playing once for 2 s: five animal heads jump, and one makes a jump clearly higher than every other. The answer is JSON the SDK writes from the click on each round, {"c": [{"x": …, "y": …, "ms": …, "p": …}, …]}: both clicks must land on the highest jumper, after its jump was on screen. The widget plays each round from a blob: URL, so a Content-Security-Policy must allow blob: in img-src. Keyboard-only users cannot solve it: keep image_distort available where accessibility matters.
- object_rotate — two JPEG strips, one per round, each 8 frames of 300 × 150 side by side. Every frame has two panels seen from the same camera, an arrow on the ground on the left and the object on the right, so the arrow never covers the object; frame k is the object turned k steps clockwise as seen from above. The person turns it a frame at a time, from frame 0, until it faces the way the arrow points, and presses Done. The answer is JSON the SDK writes from the presses, {"r": [{"f": …, "s": [[ms, d], …], "done": …}, …]}: in each round the presses must lead to the frame that faces the arrow, at a person's pace. It works with the keyboard as well as a pointer, but needs sight.
- auto_check — no image: a compact box of about 300 × 64 checks the visitor in the background while the browser solves a proof of work of 18 bits instead of 15. The answer is JSON the SDK writes from its browser checks, and the behaviour is recorded on the whole page. Most visitors pass with no action and get a token; the rest get a challenge of fallback_type in the same place. An automatic pass needs a clearance from a puzzle solved before or, in balanced mode, is a first visit, at most 5 an hour per address; an address of a cloud or hosting provider never passes automatically, and one address gets at most 30 automatic passes an hour. It is as accessible as its fallback: choose image_distort where people use a keyboard alone. What it stops and what it does not is under Auto check below.
Text answers are not case-sensitive. The plan of your account decides which types a key may request. In the JavaScript and Java SDKs, name them with ChallengeType.IMAGE_DISTORT, ChallengeType.MOTION_NOISE, ChallengeType.SLIDE_PUZZLE, ChallengeType.ANIMAL_JUMP, ChallengeType.OBJECT_ROTATE and ChallengeType.AUTO_CHECK.
See every captcha, with real samplesLimits and security
- Challenges and tokens expire after two minutes, and each works once.
- Behaviour check: with every answer the SDKs send how the pointer moved and how the answer was typed (never the keys), and from 1.3.0 a proof of work and three hints about the browser. The service also compares the address and User-Agent of the answer with those that fetched the challenge. An answer a script clearly gave, such as one typed in by a script, faster than anyone could, with a wrong proof of work or from an HTTP library, is refused even when right. Others get a verdict in /siteverify: accept human, refuse not_measured (no behaviour data was sent: an SDK older than 1.2.0 or a hand-written integration), and decide about suspicious per form, refusing it for sign-up and login.
- Allowed domains and IP addresses: on a key's page, list the websites that may use the key (shop.example.com, *.example.com for its subdomains, localhost:3000) and, if you like, the addresses or networks (such as 203.0.113.0/24). With no domains any website may use it, with no addresses every address may; 0.0.0.0 also allows every address.
- Resetting a secret key keeps the previous one valid for 24 hours, or until you revoke it, so servers can switch without downtime.
- Each account has a daily quota of successful verifications, all its keys together; the pricing page lists the quota of every plan. It resets at 00:00 GMT+7 (17:00 UTC), and once it is used up new challenges are refused until then. An automatic pass of auto_check counts like a right answer; a visitor who falls back and solves the fallback counts once.
- Rate limits, per minute: 30 challenges per IP address and 600 per key, 60 answers per IP address, and 1,200 /siteverify calls per secret key. An address with more than 20 wrong answers in 10 minutes is refused until those 10 minutes are over; an auto_check that falls back is not a wrong answer unless it was judged automated. Over a limit the reply is 429 RATE_LIMITED, with Retry-After in seconds. In front of the services, api.waucaptcha.com takes at most 120 requests a minute from one address.
- Scraping check, per key and day: a key that fetched at least 500 challenges with fewer than 10% answered, or with at least 200 answers of which fewer than 10% were right or more than half automated, is flagged and throttled to 60 challenges a minute until midnight (GMT+7). Only a key with at least 5,000 challenges in a day and fewer than 5% answered is suspended. Either way its owner can request a review on the key's page. Fetch a challenge when the widget is shown, not ahead of time: challenges never answered count against the key.
Errors
In the JavaScript SDKs, compare error.code with the ErrorCode constants, e.g. ErrorCode.SITE_KEY_INVALID; in Java, compare e.getCode() with the same constants of com.waucaptcha.ErrorCode.
Auto check
auto_check lets most visitors through without a puzzle, so be clear about what that rests on.
What a pass rests on
Every signal inside the browser, from the probes to the behaviour and the proof of work, can be faked by a determined bot that drives a real browser. So an automatic pass leans on three things such a bot cannot fake from inside the browser:
- A puzzle this browser solved on your site before: the clearance, kept up to 7 days and good for at most 6 automatic passes an hour and 24 a day.
- An address that does not belong to a cloud or hosting provider: an answer from one never passes automatically, whatever its clearance and score, and gets the fallback.
- Caps per address: 30 automatic passes an hour, at most 5 of them without a clearance.
Strict or balanced
- Strict: a visitor passes automatically only after solving one puzzle on your site in this browser. The strongest: the first visit always shows a puzzle.
- Balanced: a first visit from a home or mobile address may also pass on its signals alone, up to 5 an hour per address, with the reason first_visit.
- WAU Captcha runs in balanced mode.
What it stops
- Plain HTTP scripts, headless browsers that do not hide themselves (navigator.webdriver, a HeadlessChrome User-Agent, no outer window size, WebGL drawn in software, notifications denied while the browser says it would ask) and stealth plugins that patch browser functions or rewrite the User-Agent or the language.
- Bots in data centres, whatever they fake: they never pass automatically. Every pass also costs the client a proof of work of 18 bits, about 8 times that of the other types, and the same browser asking again is judged the same way.
What it does not stop
- A determined attacker who solves puzzles, or pays people to, earns clearances: each buys at most 6 automatic passes an hour and 24 a day, in the browser that solved it. In balanced mode, one behind home or mobile addresses also gets up to 5 first visits an hour per address. Cloudflare and Google have far more data to judge with.
- For sign-ups, logins and payments, refuse the reason first_visit on your backend, or use an interactive type for those forms.
What it costs real people
- People on a VPN or a cloud desktop always see a puzzle: their addresses belong to cloud and hosting providers.
- Clearing the site's data or a private window means one more puzzle, and so does a browser update: the clearance goes with the site's data and is tied to the browser's User-Agent.
The SDK sends the names of the checks that tripped (patched_natives, outer_zero, software_gl, notification_mismatch, touch_mismatch, no_hardware and no_plugins), navigator.userAgent and navigator.language, which every request carries in its headers already, the behaviour it records for every type, here on the whole page, and counts of how the mouse moves were made, never positions beyond what the behaviour check already sends. It stores one thing in the browser: the clearance, in localStorage under your site's origin, which goes back to WAU Captcha with auto_check answers and nowhere else. No fingerprint, canvas or WebGL output, fonts or plugins. On the service, Redis counts the automatic passes of each address for an hour, those without a clearance too, and the passes of each clearance for an hour and a day; the clearance itself is signed, not stored.
A visitor it is unsure of gets a challenge of the fallback type instead, slide_puzzle unless you name another, and is never told why. auto_check is as accessible as that fallback: choose image_distort where people use a keyboard alone.
Set data-challenge-type="auto_check" with data-fallback-type and data-appearance (always, or interaction-only to show the captcha only for the fallback or an error), or the props challengeType, fallbackChallengeType and appearance of <WauCaptcha />:
<div data-wau-captcha data-site-key="pk_…" data-base-url="https://api.waucaptcha.com" data-challenge-type="auto_check" data-fallback-type="image_distort" data-appearance="interaction-only"></div>What your backend can check
/siteverify reports challenge_type auto_check for an automatic pass, and the fallback's type for a visitor who solved the fallback. behavior.reasons says how an automatic pass was earned: cleared, by a browser that solved a puzzle on your site before, or first_visit, on its signals alone. Refusing first_visit for sign-ups, logins and payments makes balanced mode as strong as strict where it matters:
const result = await wau.verifyToken(token);if (!result.success || !hostnameMatches(result.hostname, process.env.WAU_ALLOWED_HOSTNAMES)) { throw new Error("Please solve the captcha.");}// Passed auto_check on its signals alone, without a puzzle: a sign-up asks for one instead.if (result.behavior.reasons.includes("first_visit")) { // e.g. show the form again with challengeType slide_puzzle}In the usage charts, the success rate of auto_check is the share of visitors who passed without a puzzle.
Read the auto_check guideLimitations
What the service does not catch, so you can weigh it against your risk:
- TLS (JA3, JA4) and HTTP/2 fingerprints: Traefik ends TLS in front of the services and does not pass them on.
- auto_check: a real browser driven with human-like input passes the automatic check with a clearance earned by solving a puzzle, or in balanced mode as a first visit from a home or mobile address; for sign-ups, logins and payments, refuse first_visit or ask for an interactive type.
- Paid IP reputation feeds: the service only keeps its own short history of each address.
- slide_puzzle: image matching finds where the hole is; its value is in the drag, which must move like a hand.
- animal_jump: a script that analyses the frames can find the highest jump; a random click passes 1 time in 25, but most of its value lies in the behaviour and timing checks.
- object_rotate: a script trained on the 10 objects could learn which way each one faces; random presses pass about 1 time in 64, but most of its value lies in the behaviour and timing checks.
- motion_noise: a script that compares the frames can bring the characters out; it stops tools that read a single picture.
- Text challenges: a model trained on these images can read many of them. Each challenge can be answered once, so a code cannot be brute-forced, and the per-address limits slow down guessing across challenges.
- Origin and the browser hints can be forged by a script outside a browser.
- No CAPTCHA stops a determined attacker on its own: use it together with rate limits and checks of your own on the actions that matter.