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 fails

Tips 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.

index.htmlhtml
<!-- 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.

index.htmlhtml
<!-- 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-keyrequired

Your site key from the dashboard (e.g. gc_xxxxx).

data-gamerequired

Game 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:loaded fires when the game is playable. Detail: { gameId, siteKey }.
  • gamecaptcha:error fires when the game cannot load. Detail: { gameId, siteKey, reason }, where reason is lapsed (protection paused until the owner renews), invalid_site_key or unavailable.

How Verification Works

The token flow in 5 steps.

1

Widget loads

The script tag renders the game inside the div. The player's site key is read from the data-site-key attribute.

2

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.

3

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.

4

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.

5

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.

POST/api/verify

Request headers

Authorization: Bearer YOUR_API_KEYContent-Type: application/json

Request body

{ "token": "...", "siteKey": "gc_..." }

✅ Success response

{ "success": true, "gameId": "whackabot", "hostname": "example.com" }

❌ Failure response

{ "success": false, "error": "Invalid or expired token" }
  • hostname is the hostname where the game was played, normally your site's hostname, as reported by the visitor's browser, or null when 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_token field stays empty.
  • On your server, keep the timeout from the samples. A timeout or a 5xx reply means the token was not checked, and success is 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.

GAMEAVG. TIMEDIFFICULTYBEST FORMOBILE
🔴Four in a Row10sEasyGeneral signups✓
🍒Maze Muncher8sEasyGaming sites✓
🔨Whack-a-Bot6sEasyLogin forms✓
🎨Color Match7sEasySignup flows✓
🌀Maze Runner10sMediumHigh-security forms✓
🍎Fruit Sorter8sEasyE-commerce checkouts✓
🧱Stack It10sEasyComment forms✓
🫧Tap in Order6sEasyCheckout flows✓
🔧Pipe Connect12sMediumAccessibility-first sites✓
🏓Brick Breaker10sMediumGaming & community sites✓
⚽Penalty Kick8sEasySports & ticketing✓
🟪Tetromino Drop15sMediumHigh-security forms✓
⛳Mini Golf Putt12sMediumLeisure & booking sites✓
🚀Asteroid Dodge8sMediumGaming & tech sites✓
🎯Ring Roll12sMediumRetail & arcade brands✓
🏀Hoops10sMediumSports & ticketing✓
🐸Road Hopper12sMediumGeneral signups✓
🦆Duck Pop10sEasyLogin 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.

POST/api/verify🔑 Auth required

Verify 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.

POST/api/game-complete

Called by the embed widget internally. Returns a signed JWT on game pass.

GET/api/auth/me🔑 Auth required

Get the current authenticated user, their API key, and owned games. Uses your dashboard sign-in session, not the API key.

GET/api/me/analytics🔑 Auth required

Solve 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.

POST/api/me/api-key🔑 Auth required

Rotate your API key. The old key stops working immediately; the new key is returned once. Uses your dashboard sign-in session.

GET/api/health

Service health for uptime monitors. 200 when app + database are reachable, 503 otherwise.