Supabase Auth ships with a great signup endpoint and almost no bot-protection out of the box. This guide walks through adding a Playtcha verification step to a Next.js + Supabase signup flow, covering the form widget, the Server Action, and the RLS gotchas that catch most teams.
What bots do to a Supabase app
The default Supabase signup endpoint is POST /auth/v1/signup. It accepts an email and password and creates an unconfirmed user. By default it triggers a confirmation email. For a bot, that’s a free dispatch from your sender domain — and a fast way to land on a major email provider’s blocklist.
The three abuse patterns we see most often:
- Email-spam relay. Bots iterate target addresses to fire your confirmation email at them. Your sender reputation tanks within hours.
- Free-tier farming. If your app gives signup credits or a free trial, bots harvest accounts at scale.
- Database pollution. Tens of thousands of unconfirmed
auth.usersrows make your dashboard unreadable and your weekly active-user metric a lie.
If the upstream question of whether you actually need a CAPTCHA is still open, see why use a CAPTCHA. For this guide, we assume yes — your signup endpoint is exposed, and you want a verification gate.
The integration shape
Three pieces of code change. None of them touch your Supabase schema in a load-bearing way (RLS hardening is optional — see step 4).
- The signup form mounts the Playtcha widget; on success it stashes a token in a hidden field.
- Your Server Action (or API route) reads the token, calls Playtcha’s
/v1/verify, and only then calls Supabase’ssignUp. - An optional defense-in-depth: do the verify inside a Supabase Edge Function so the secret never leaves Supabase.
The whole thing is roughly 30 lines of new code. We’ll walk each one.
Step 1: drop the widget into your form
Add the Playtcha loader once in your root layout, then mount the widget inside the form Server Component. The widget writes its verification token into a hidden input named playtcha-token.
// app/layout.tsx
import Script from "next/script";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<Script
src="https://playtcha.com/v1/widget.js"
strategy="afterInteractive"
/>
{children}
</body>
</html>
);
}// app/signup/page.tsx
import { signUpAction } from "./actions";
export default function SignupPage() {
return (
<form action={signUpAction}>
<label>
Email
<input name="email" type="email" required autoComplete="email" />
</label>
<label>
Password
<input name="password" type="password" required autoComplete="new-password" />
</label>
{/*
The widget mounts here. On success it sets the value of an input
named "playtcha-token" inside this div, which the form will
submit to the action.
*/}
<div className="playtcha" data-sitekey={process.env.NEXT_PUBLIC_PLAYTCHA_KEY!}></div>
<button type="submit">Create account</button>
</form>
);
}That’s the whole client-side change. The widget handles the game UI, posts to Playtcha’s issuer, receives a result token, and writes that token into the form for submission.
Step 2: verify in your Server Action
The Server Action is where the security gate actually lives. The client-side widget is convenience; the server-side verify is the contract. Skip the verify and an attacker can fake the token in DevTools.
// app/signup/actions.ts
"use server";
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";
import { redirect } from "next/navigation";
export async function signUpAction(formData: FormData) {
const email = String(formData.get("email") ?? "");
const password = String(formData.get("password") ?? "");
const playtchaToken = String(formData.get("playtcha-token") ?? "");
// 1. Verify the human gate before doing anything else.
if (!playtchaToken) {
redirect("/signup?error=captcha_missing");
}
const verifyRes = await fetch("https://playtcha.com/v1/verify", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
secret: process.env.PLAYTCHA_SECRET!,
token: playtchaToken,
}),
// Tight timeout — Playtcha's p99 is well under 1s. Fail closed if not.
signal: AbortSignal.timeout(3000),
});
const { ok } = (await verifyRes.json()) as { ok: boolean };
if (!ok) {
redirect("/signup?error=captcha_failed");
}
// 2. Only now create the user.
const cookieStore = await cookies();
const supabase = createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{ cookies: { getAll: () => cookieStore.getAll(), setAll: () => {} } },
);
const { error } = await supabase.auth.signUp({ email, password });
if (error) {
redirect(`/signup?error=${encodeURIComponent(error.message)}`);
}
redirect("/signup/check-email");
}Notes on the shape:
- The verify is the first thing the Server Action does. We don’t want to spend a Supabase call on a request that will fail the human gate.
AbortSignal.timeout(3000)bounds your blast radius if Playtcha is degraded. We discuss the failure-mode tradeoff in the FAQ below.- The error redirects use a query param. In production you probably want a more thoughtful UX with the form values preserved.
Step 3 (optional): verify inside a Supabase Edge Function
If you don’t want your Playtcha secret to live in your Next.js env at all — for example, you’re running on a platform you don’t control end-to-end — push the verify into a Supabase Edge Function. The shape is the same; the secret moves to supabase secrets.
// supabase/functions/verify-captcha/index.ts
import "jsr:@supabase/functions-js/edge-runtime.d.ts";
Deno.serve(async (req) => {
const { token } = await req.json();
if (!token) return new Response("missing token", { status: 400 });
const r = await fetch("https://playtcha.com/v1/verify", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
secret: Deno.env.get("PLAYTCHA_SECRET"),
token,
}),
});
const { ok } = await r.json();
return new Response(JSON.stringify({ ok }), {
status: ok ? 200 : 401,
headers: { "Content-Type": "application/json" },
});
});# Deploy + add the secret
supabase functions deploy verify-captcha
supabase secrets set PLAYTCHA_SECRET=sk_live_...Your Server Action then calls the Edge Function instead of Playtcha directly. The benefit: your Next.js process never sees the Playtcha secret, and you have one Supabase-side audit trail for every verify attempt.
Step 4: tighten RLS so the verify is load-bearing
The verify gate above protects your Server Action. It does not protect anyone who calls the Supabase signup endpoint directly with the public anon key — which is, sadly, the default.
Two ways to make the verify actually load-bearing:
Option A: turn off public signups, force everyone through your action
In the Supabase dashboard, set Auth » Settings » Disable signup. Then perform the actual signUp using the Supabase service-role key inside your Server Action (after the Playtcha verify has succeeded). The anon key can no longer create users at all, so a bot bypassing your Next.js layer hits a dead endpoint.
This is the cleanest separation but trades flexibility — any future signup flow has to go through your action.
Option B: keep public signups on, gate downstream tables
Add a column on your profiles (or equivalent) table that records whether the user passed a Playtcha check, and write RLS policies that exclude unverified users from anything meaningful. Bots can still create auth.users rows but can’t reach your real product surface.
We prefer Option A in new builds. If you’re retrofitting an existing app where many flows touch auth.signUp, Option B is the more pragmatic path.
Common pitfalls
The widget mounts but the token never reaches the action
Almost always a hydration order issue: the loader script runs after the form has been submitted. Use strategy="afterInteractive" on the Next<Script> component (as in step 1), and disable the submit button until you see the token populate.
Verify works locally but fails in production
Check the allowed_domains list on your Playtcha project. The public key is only valid on registered domains. The easy fix is to add your production hostname (and any preview deploys) to the list in the dashboard.
The Server Action redirects to /signup?error=captcha_failed on every submit
Most often a clock-skew issue on a self-hosted Vercel alternative — Playtcha tokens are time-bounded and we reject anything more than a few minutes off. Less commonly, the secret is wrong. Check process.env.PLAYTCHA_SECRET isn’t empty.
Conversion drops on Android Chrome
If you’re seeing a conversion dip on low-end Android, you can A/B against an alternate CAPTCHA — see reCAPTCHA alternatives — but in practice the dip is usually a separate issue (form layout, autofill, password manager) being unmasked by the change. Profile before re-architecting.
Once this is shipped, the same shape applies to your password-reset and contact-form endpoints. The widget, the verify call, and the Server Action are the same; only the form changes. For the broader compliance picture (sub-processor list, DPA, residency), see the GDPR CAPTCHA checklist. For the privacy posture this gives you, see privacy-first CAPTCHAs explained. If your auth page’s Lighthouse score has been sliding, the diagnostic is in why your CAPTCHA shouldn’t be 250 KB — the migration in this guide is also a bundle-budget win.
Testing this locally without sending fake verifies
A nice-to-have during development is to short-circuit the Playtcha verify against test keys so you can iterate on the Server Action without consuming your real-project quota. Two patterns work well:
- Test site keys. Generate a separate Playtcha project specifically for local development with
localhostin the allowed-domains list. Use a different env file (.env.local) to hold those keys. The verifies still hit the real Playtcha endpoint but the project stays out of your production analytics. - Mock the verify in tests. In automated tests, intercept the
fetchtohttps://playtcha.com/v1/verifywithmswor your testing library’s equivalent and return{"ok": true}for known-good fixture tokens.
We deliberately don’t ship a “test mode” secret that always returns ok: true regardless of token, because the resulting integration is one that doesn’t actually verify in production if the wrong env-var slips through. The two patterns above give you the same dev-loop speed without that footgun.
FAQ
What if Playtcha is down? Do my signups break?
Yes, by default — the verify call fails, the Server Action redirects to an error, the user can’t sign up. That’s the safe default (fail closed). If you’d rather fail open for a specific endpoint (e.g. accept signups during a Playtcha outage and rely on rate limiting), wrap the verify call in a try/catch and treat a non-response as a soft pass. Wedon’t recommend doing this on payment-intent or high-value endpoints.
Can I do this with the Supabase JavaScript client only?
Mostly. You can call Playtcha’s /v1/verify from the client, but then your secret would be in the browser, which defeats the security guarantee. The verify must happen on a server you control — either a Server Action, an API route, or a Supabase Edge Function. There’s no client-only safe shape.
Does this work with Supabase Auth UI / pre-built components?
Not directly — the pre-built Auth UI doesn’t have a Playtcha extension point. The pattern in this guide assumes you’re building your own form. If you want to keep the pre-built UI, you’ll need to wrap it with your own submit-handler that does the verify before the underlyingsignUp fires.
Can I use this with magic-link signups?
Yes. The shape is identical: verify the Playtcha token in the Server Action, then call auth.signInWithOtp. This is actually one of the highest-value places to add a CAPTCHA because magic-link is an email-blast vector if left unprotected.
Where do I store the keys in development?
A .env.local file with NEXT_PUBLIC_PLAYTCHA_KEY and PLAYTCHA_SECRET. Make sure .env.local is in your .gitignore (it is by default in Next.js). The public key is safe in HTML; the secret never goes anywhere a browser can reach.
