Bots hit auth endpoints constantly. Login forms, magic links, signup codes — anything that talks to a database or sends an email is a target. Rate limiting helps, but sophisticated bots rotate IPs and fingerprints. You need something that runs a challenge in the browser before the request ever reaches your server.

Vercel BotID does this. It runs a client-side challenge on routes you specify, attaches proof-of-humanity headers to the request, and gives you a server-side check that classifies the session as human or bot. If it’s a bot, you reject the request before doing any expensive work.

I added it to 0xInsider to protect the auth flow — magic link sends, token verification, signup codes. Here’s how it works.

The architecture

My setup is a Next.js 16 frontend on Vercel that proxies API calls to a Rust backend on Railway. The proxy lives in proxy.ts middleware — it rewrites /api/auth/* requests to the backend with an API key header.

The problem: BotID’s checkBotId() function only works inside Next.js server context (route handlers or server actions). It can’t run in middleware. So I can’t just drop it into the existing proxy.

The solution: thin Next.js route handlers that sit between the client and the backend proxy.

1
  Browser
2
    │
3
    │  fetch("/api/botid/magic-link")
4
    │  (BotID challenge headers attached automatically)
5
    │
6
    ▼
7
  Next.js route handler
8
    │
9
    │  checkBotId() → is this a bot?
10
    │
11
    ├── YES → 403 Blocked
12
    │
13
    └── NO → proxy to Railway backend
14
              POST /api/auth/magic-link

The client-side BotID script intercepts fetch requests to protected routes and attaches challenge headers. The server-side checkBotId() reads those headers and classifies the session. If it passes, the route handler manually proxies to the backend — same as what proxy.ts does, but with the bot check first.

Install the package and wrap your Next.js config:

1
npm i botid

1
import { withBotId } from "botid/next/config";
2
import type { NextConfig } from "next";
3

4
const nextConfig: NextConfig = {
5
  // your existing config
6
};
7

8
export default withBotId(nextConfig);

withBotId adds proxy rewrites that serve BotID’s challenge script from your own domain. This matters because ad-blockers can’t fingerprint it as a third-party bot-detection script.

Next, register the routes you want to protect. Next.js 16 supports instrumentation-client.ts for client-side initialization:

1
import { initBotId } from "botid/client/core";
2

3
initBotId({
4
  protect: [
5
    { path: "/api/botid/magic-link", method: "POST" },
6
    { path: "/api/botid/verify", method: "POST" },
7
    { path: "/api/botid/validate-code", method: "POST" },
8
    { path: "/api/botid/redeem-code", method: "POST" },
9
  ],
10
});

When the browser makes a POST to any of these paths, BotID’s client script intercepts it, solves a challenge, and attaches the result as headers. This happens transparently — no UI, no CAPTCHA.

On the server side, I wrote a shared helper that every route handler uses:

1
import { checkBotId } from "botid/server";
2
import { NextRequest, NextResponse } from "next/server";
3

4
const API_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:8080";
5
const API_KEY = process.env.API_SECRET_KEY ?? "";
6

7
export async function verifyAndProxy(
8
  request: NextRequest,
9
  backendPath: string,
10
): Promise<NextResponse> {
11
  const verification = await checkBotId();
12

13
  if (verification.isBot && !verification.isVerifiedBot) {
14
    return NextResponse.json({ error: "Blocked" }, { status: 403 });
15
  }
16

17
  const body = await request.text();
18
  const headers: Record<string, string> = {
19
    "Content-Type": "application/json",
20
  };
21
  if (API_KEY) headers["x-api-key"] = API_KEY;
22

23
  const clientIp = request.headers
24
    .get("x-forwarded-for")
25
    ?.split(",")[0]
26
    ?.trim();
27
  if (clientIp) headers["x-real-ip"] = clientIp;
28

29
  const res = await fetch(`${API_URL}${backendPath}`, {
30
    method: "POST",
31
    headers,
32
    body,
33
  });
34

35
  const data = await res.text();
36
  return new NextResponse(data, {
37
    status: res.status,
38
    headers: { "Content-Type": "application/json" },
39
  });
40
}

checkBotId() reads the challenge headers from the incoming request automatically — no arguments needed in Next.js. If the session is a bot and not a verified bot, we return 403 immediately. If it’s human or a verified bot (like ChatGPT Operator or Perplexity — see the full directory at bots.fyi), we forward everything to the backend exactly like the proxy middleware would.

Each route handler is four lines:

1
import type { NextRequest } from "next/server";
2
import { verifyAndProxy } from "../_proxy";
3

4
export async function POST(request: NextRequest) {
5
  return verifyAndProxy(request, "/api/auth/magic-link");
6
}

Same pattern for /verify, /validate-code, and /redeem-code. Each one maps to a backend auth endpoint.

The last piece: tell your proxy middleware to leave these routes alone. If you have a middleware that rewrites /api/* routes to your backend (like I do), you need to exclude /api/botid/* so the route handlers actually run:

1
const ROUTE_HANDLER_ROUTES: string[] = ["/api/botid"];

Then update your frontend auth calls to hit the new paths:

1
// Before
2
authFetch("/api/auth/magic-link", { method: "POST", body });
3

4
// After
5
authFetch("/api/botid/magic-link", { method: "POST", body });

What happens locally

BotID always returns isBot: false in development. Your auth flow works exactly the same — the bot check just passes through. If you want to test the blocking behavior locally, pass developmentOptions:

1
const verification = await checkBotId({
2
  developmentOptions: { bypass: "BAD-BOT" },
3
});

In production, BotID has two tiers. Basic is free and uses client/network signals. Deep Analysis costs $1 per 1,000 checks and does asynchronous investigation of suspicious sessions. You enable Deep Analysis in the Vercel dashboard under Firewall → Rules — it’s a toggle, not a code change.

For auth endpoints that send emails or hit a database, $1 per 1,000 checks is worth it. A single bot that signs up 10,000 fake accounts costs way more in email sends and database bloat.

Handling verified bots

Not all bots are bad. ChatGPT Operator, Perplexity, and other AI assistants are verified bots that you probably want to let through. BotID (v1.5.0+) tells you when a bot is verified via isVerifiedBot, verifiedBotName, and verifiedBotCategory.

That’s why the check above uses verification.isBot && !verification.isVerifiedBot — it blocks scrapers and credential stuffers while letting verified bots interact with your app normally. Vercel maintains a directory of verified bots at bots.fyi.

If you need finer control, you can check verifiedBotName directly:

1
const { isBot, isVerifiedBot, verifiedBotName } = await checkBotId();
2

3
// Only allow specific verified bots
4
const allowedBots = ["chatgpt-operator", "perplexitybot"];
5
const isAllowed = isVerifiedBot && allowedBots.includes(verifiedBotName ?? "");
6

7
if (isBot && !isAllowed) {
8
  return NextResponse.json({ error: "Blocked" }, { status: 403 });
9
}