DOCUMENTATION
Integration Guide
Everything you need to embed CaptchaKit in your signup forms and verify tokens on your server.
Integrate with Claude Code
The fastest way to add CaptchaKit to your app
Copy the prompt below, fill in your site key and API key from your dashboard, and paste it into Claude Code. Claude will find your form, add the widget, and wire up server-side verification.
I'm adding CaptchaKit to my app. CaptchaKit replaces the standard CAPTCHA checkbox with a short arcade game: visitors play it in the form, and my server verifies a signed, single-use token before it accepts the submission.
How it works:
- A <script> tag loads the widget from https://captchakit.com/widget.js
- A <div data-gamecaptcha data-site-key="..." data-game="whackabot"> renders the game inside my form (both attributes are required)
- When the player passes, the signed token is stored on the div's data-token attribute and in a hidden input named gamecaptcha_token in the parent form, and a gamecaptcha:pass event bubbles up to document
- The widget div fires gamecaptcha:loaded when the game is playable, and gamecaptcha:error with detail.reason ("lapsed", "invalid_site_key" or "unavailable") when it cannot load
- I must verify the token server-side before processing the form: POST https://captchakit.com/api/verify with header Authorization: Bearer <api_key> and JSON body { "token": "...", "siteKey": "..." }. The JSON response is { "success": true, "gameId": "...", "hostname": "..." } or { "success": false, "error": "..." }
- hostname is the hostname where the game was played, normally your site's hostname, as reported by the visitor's browser (null when it sent none). It is informational only: log it or flag a mismatch, comparing against both my apex and www hosts, but never use it to grant access
- A pass can also carry "warning": "subscription_lapsed": my subscription has lapsed and is in its grace period. Treat it as a pass, and show my admins a notice to renew
- "error": "subscription_lapsed" means protection is paused until I renew, so no token passes. Show my admins a notice to renew
- Tokens expire in 10 minutes and can only be used once
My credentials (from my CaptchaKit dashboard at captchakit.com/dashboard):
- Site key: [PASTE YOUR SITE KEY, starts with gc_]
- API key: [PASTE YOUR API KEY, starts with cgv_]
- Game I want to use: whackabot
Please:
1. Add the CaptchaKit widget.js script to my page
2. Add the widget div inside my existing form where the CAPTCHA should go
3. Update my form submit handler to read the token and block submission if it's missing
4. Add server-side token verification in my form handler, and reject the request if verification failsTips for best results
- • Paste your actual site key and API key, and Claude will put them in the right places
- • Tell Claude which specific form or file to modify if your project has more than one
- • If Claude asks to install a package, there is no npm package. The widget is a plain script tag
- • After Claude makes changes, run your dev server and play a game to confirm the token is being sent
Quick Start
The simplest possible integration: two lines of HTML, one verification call.
<!-- Step 1: Add CaptchaKit script to your page (before </body>) -->
<script src="https://captchakit.com/widget.js"></script>
<!-- Step 2: Add the widget inside your form -->
<form id="signup-form">
<input type="email" name="email" placeholder="Email" />
<div
data-gamecaptcha
data-site-key="gc_whackabot_your_key_here"
data-game="whackabot"
></div>
<button type="submit">Sign up</button>
</form>
<!-- Step 3: Read the token on submit -->
<script>
document.getElementById('signup-form').addEventListener('submit', async (e) => {
e.preventDefault();
const token = e.target.querySelector('[data-gamecaptcha]').dataset.token;
if (!token) return alert('Please complete the game first.');
const res = await fetch('/api/signup', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email: e.target.email.value, gamecaptcha_token: token }),
});
});
</script>IMPORTANT
Always verify the token on your server before processing form submissions. Client-side checks alone are insufficient, because a bot could submit directly to your API.
embed.js Script Tag
The embed.js approach works in any HTML page, with no bundler and no framework required. Drop a single <script> tag, add the widget div, and listen for the gamecaptcha:pass event.
<!-- 1. Load the script (once, anywhere on the page) -->
<script src="https://captchakit.com/widget.js" async></script>
<!-- 2. Drop the widget div wherever you want it in your form -->
<form id="my-form">
<input type="email" name="email" placeholder="Email address" />
<div data-gamecaptcha data-site-key="gc_whackabot_xxxxx" data-game="whackabot"></div>
<button type="submit">Sign up</button>
</form>
<!-- 3. Listen for the gamecaptcha:pass event to read the token -->
<script>
document.addEventListener('gamecaptcha:pass', function (e) {
var token = e.detail.token;
// Store it so your submit handler can read it
document.getElementById('my-form').dataset.gcToken = token;
});
document.getElementById('my-form').addEventListener('submit', async function (e) {
e.preventDefault();
var token = this.dataset.gcToken;
if (!token) {
alert('Please complete the game first.');
return;
}
// Send the token to your server for verification
await fetch('/api/signup', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: this.email.value,
gamecaptcha_token: token,
}),
});
});
</script>DATA ATTRIBUTES
data-site-keyrequiredYour site key from the dashboard (e.g. gc_xxxxx).
data-gamerequiredGame ID to show. Without it the widget shows an error and loads no game. Use a game your plan includes. Options: connect4, pacman, whackabot, colormatch, mazerunner, fruitsorter, stackit, tapinorder, pipeconnect, brickbreaker, penaltykick, tetrodrop, minigolf, asteroiddodge, skeeball, hoops, frogger, duckhunt.
gamecaptcha:pass EVENT DETAIL
{ token: string, gameId: string, siteKey: string }The event fires on the widget div and bubbles up to document. Send the token to your server and verify it with POST /api/verify.
OTHER EVENTS
gamecaptcha:loadedfires when the game is playable. Detail:{ gameId, siteKey }.gamecaptcha:errorfires when the game cannot load. Detail:{ gameId, siteKey, reason }, wherereasonislapsed(protection paused until the owner renews),invalid_site_keyorunavailable.
How Verification Works
The token flow in 5 steps.
Widget loads
The script tag renders the game inside the div. The player's site key is read from the data-site-key attribute.
Player passes the game
When the human wins, the widget calls our server with the site key. The server confirms the key is valid and issues a signed JWT.
Token written to the element
The signed token is stored in data-token on the widget div and in a hidden input named gamecaptcha_token in the parent form. Your form submit handler reads it.
You verify server-side
Your server calls POST /api/verify with the token and your site key, sending your API key in the Authorization header. Never make this call from the browser.
You act on the result
We return { success: true, gameId, hostname }, plus warning: "subscription_lapsed" during a grace period, or { success: false, error } (error: "subscription_lapsed" once protection is paused). Only process the form on success.
Token format (JWT, expires in 10 minutes)
{ siteKey: "gc_whackabot_xxx", gameId: "whackabot", type: "game_pass", hostname: "example.com", jti: "...", iat: ..., exp: ... }hostname is present only when the browser reported the embedding site.
Server Verification
Call this endpoint from your server, never from the browser.
/api/verifyRequest headers
Authorization: Bearer YOUR_API_KEYContent-Type: application/jsonRequest body
{ "token": "...", "siteKey": "gc_..." }✅ Success response
{ "success": true, "gameId": "whackabot", "hostname": "example.com" }❌ Failure response
{ "success": false, "error": "Invalid or expired token" }hostnameis the hostname where the game was played, normally your site's hostname, as reported by the visitor's browser, ornullwhen it sent none. It is informational only. If you log or flag it, compare it against both your apex and www hosts, and never use it to grant access."warning": "subscription_lapsed"on a pass means your subscription has lapsed and is in its grace period. Treat it as a pass, and show your admins a notice to renew."error": "subscription_lapsed"means protection is paused until you renew, so no token passes. Show your admins a notice to renew.
// Express example
app.use(express.json()); // fetch() JSON posts
app.use(express.urlencoded({ extended: false })); // plain HTML form posts
app.post('/api/signup', async (req, res) => {
const { email, gamecaptcha_token } = req.body;
// Verify the token server-side
const verifyRes = await fetch('https://captchakit.com/api/verify', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY', // from your dashboard
},
body: JSON.stringify({
token: gamecaptcha_token,
siteKey: 'gc_whackabot_your_key_here',
}),
});
const result = await verifyRes.json().catch(() => ({}));
if (result.success !== true) {
return res.status(400).json({ error: 'CAPTCHA check failed. Please try again.' });
}
// Token is valid: proceed with signup
await createUser(email);
res.json({ ok: true });
});If CaptchaKit can't be reached
- In the browser, the widget shows "CaptchaKit could not load." with a Try again button. No token is written, so the
gamecaptcha_tokenfield stays empty. - On your server, keep the timeout from the samples. A timeout or a 5xx reply means the token was not checked, and
successis never true in that case. - What happens next is your call. Reject the form and ask the visitor to play again on login, signup and checkout. Accepting it and flagging it for review can be fine on a contact form.
- A token works once and expires 10 minutes after the game, so a retry needs a fresh game.
Framework Guides
Complete examples for the most common stacks.
import { useEffect, useRef, useState } from 'react';
declare global {
interface Window { GameCaptcha?: { init: () => void } }
}
const WIDGET_SRC = 'https://captchakit.com/widget.js';
export default function SignupForm() {
const widgetRef = useRef<HTMLDivElement>(null);
const [loading, setLoading] = useState(false);
// Load the widget script once. If it is already on the page,
// re-scan so the widget mounts in this newly rendered div.
useEffect(() => {
if (document.querySelector(`script[src="${WIDGET_SRC}"]`)) {
window.GameCaptcha?.init();
return;
}
const script = document.createElement('script');
script.src = WIDGET_SRC;
document.body.appendChild(script);
}, []);
const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
e.preventDefault();
const token = widgetRef.current?.dataset.token;
if (!token) {
alert('Please complete the game first!');
return;
}
setLoading(true);
const res = await fetch('/api/signup', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
email: (e.target as HTMLFormElement).email.value,
gamecaptcha_token: token,
}),
});
setLoading(false);
if (res.ok) window.location.href = '/welcome';
};
return (
<form onSubmit={handleSubmit}>
<input type="email" name="email" required />
<div
ref={widgetRef}
data-gamecaptcha
data-site-key="gc_whackabot_your_key_here"
data-game="whackabot"
/>
<button type="submit" disabled={loading}>
{loading ? 'Signing up...' : 'Sign up'}
</button>
</form>
);
}Game Comparison
Choose the game that fits your form and audience.
| GAME | AVG. TIME | DIFFICULTY | BEST FOR | MOBILE |
|---|---|---|---|---|
| 🔴Four in a Row | 10s | Easy | General signups | ✓ |
| 🍒Maze Muncher | 8s | Easy | Gaming sites | ✓ |
| 🔨Whack-a-Bot | 6s | Easy | Login forms | ✓ |
| 🎨Color Match | 7s | Easy | Signup flows | ✓ |
| 🌀Maze Runner | 10s | Medium | High-security forms | ✓ |
| 🍎Fruit Sorter | 8s | Easy | E-commerce checkouts | ✓ |
| 🧱Stack It | 10s | Easy | Comment forms | ✓ |
| 🫧Tap in Order | 6s | Easy | Checkout flows | ✓ |
| 🔧Pipe Connect | 12s | Medium | Accessibility-first sites | ✓ |
| 🏓Brick Breaker | 10s | Medium | Gaming & community sites | ✓ |
| ⚽Penalty Kick | 8s | Easy | Sports & ticketing | ✓ |
| 🟪Tetromino Drop | 15s | Medium | High-security forms | ✓ |
| ⛳Mini Golf Putt | 12s | Medium | Leisure & booking sites | ✓ |
| 🚀Asteroid Dodge | 8s | Medium | Gaming & tech sites | ✓ |
| 🎯Ring Roll | 12s | Medium | Retail & arcade brands | ✓ |
| 🏀Hoops | 10s | Medium | Sports & ticketing | ✓ |
| 🐸Road Hopper | 12s | Medium | General signups | ✓ |
| 🦆Duck Pop | 10s | Easy | Login forms | ✓ |
Accessibility
WCAG 2.1 requires an alternative for any CAPTCHA. CaptchaKit ships one built in, with no extra integration work on your side.
Built-in accessible check
Every widget shows a "Can't play? Accessible check" link that switches to a screen-reader-friendly question. Passing it issues the exact same one-time token, so your server-side verification flow is unchanged.
Keyboard play
All games are fully keyboard-playable (arrows, space, enter, or number keys; each game shows its controls in the footer) and announce progress to screen readers via live regions.
🕹️ Arcade: visitors pick their game
Own more than one game? The widget automatically shows a "Switch game" button that opens a tile view of every game you own, on every platform, since it lives inside the widget itself. Visitors complete whichever they like; your site key, embed code, and server-side verification stay exactly the same. Prefer pinning each form to one game? Turn Arcade off in your dashboard.
Webhooks
Business accounts can receive signed real-time events at their own endpoints. Manage them from the dashboard. Events: verification.passed, verification.failed, game.solved.
Signature verification
Each delivery includes an X-CaptchaKit-Signature header: t=<unix-ms>,v1=<hex> where v1 is the HMAC-SHA256 of "<t>.<raw body>" using your endpoint's signing secret (shown once at creation).
Endpoints that fail 20 deliveries in a row are disabled automatically; re-add them from the dashboard when fixed.
API Reference
All endpoints at a glance.
/api/verify🔑 Auth requiredVerify a game completion token. Tokens are one-time-use: a second verify of the same token returns success: false ("Token already used"). A pass returns gameId and hostname (browser reported, informational only), plus warning: "subscription_lapsed" during a grace period. error: "subscription_lapsed" means protection is paused. Requires Authorization: Bearer header.
/api/game-completeCalled by the embed widget internally. Returns a signed JWT on game pass.
/api/auth/me🔑 Auth requiredGet the current authenticated user, their API key, and owned games. Uses your dashboard sign-in session, not the API key.
/api/me/analytics🔑 Auth requiredSolve counts, verification totals and pass rate. ?days=7 on every plan; ?days=30 or 90, daily series and per-game breakdowns on Business. Uses your dashboard sign-in session.
/api/me/api-key🔑 Auth requiredRotate your API key. The old key stops working immediately; the new key is returned once. Uses your dashboard sign-in session.
/api/healthService health for uptime monitors. 200 when app + database are reachable, 503 otherwise.