Quick Start

Add bot protection to your site in three steps: create keys in the Squeaker dashboard, embed the widget, verify on your app server.

Hosted on squeaker.cc. No servers to deploy — Squeaker runs the API, widget CDN, and dashboard. You only embed the snippet and verify tokens on your backend.
Demo credentials (local dev): demo@squeaker.local / demo-demo-demo · site key sq_live_demo

1. Create a site and get your keys

  1. Open the dashboard and sign up or log in.
  2. Click New site and enter a name (e.g. "Production" or "Staging").
  3. Add allowed domains - only these origins can use your site key (e.g. yourdomain.com, www.yourdomain.com).
  4. Copy the site key (public, goes in HTML) and secret key (private, server only).
  5. Set a protection level (1–5, default 3) — controls PoW hardness, behavior sampling, and integrity checks.

The secret key is shown once. Store it in your environment variables - never commit it to git.

2. Embed the widget

Add the script and widget element to any page with a form you want to protect:

<form id="contact-form">
  <squeaker-widget
    data-sitekey="sq_live_your_key"
    data-api="https://api.squeaker.cc/v1"
    data-mode="auto"
    data-form="#contact-form"
    data-theme="light"
  ></squeaker-widget>
  <button type="submit">Send message</button>
</form>

<script src="https://cdn.squeaker.cc/squeaker.js" async defer></script>

What happens on submit (auto mode)

3. Verify on your server

Never trust the browser alone. POST the token to the Squeaker API — no npm package required.

const apiUrl = process.env.SQUEAKER_API_URL ?? 'https://api.squeaker.cc/v1';
const token = req.body['squeaker-token'];
if (!token) return res.status(400).json({ error: 'Missing token' });

const verifyRes = await fetch(`${apiUrl}/verify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    secret: process.env.SQUEAKER_SECRET,
    token,
    remoteip: req.ip,
  }),
});
const result = await verifyRes.json();
if (!result.success) {
  return res.status(403).json({ error: result.error ?? 'Verification failed' });
}

// Token is valid - process the form

What the API checks

CheckWhat it does
Signature + expiryToken was issued for your site and is still valid
One-time useReplay protection — each token works once
AnalyticsSuccessful verifies appear in your dashboard

Environment variables (app server)

SQUEAKER_SECRET=sq_secret_your_key_here
SQUEAKER_API_URL=https://api.squeaker.cc/v1

SQUEAKER_SECRET is the secret key from the dashboard. SQUEAKER_API_URL points at the Squeaker API. These live on the server that processes your forms.

Next steps