Vercel BotID: The Invisible Bot Protection You Needed

Nowadays, bots do not act like “bots”. They can execute JavaScript, solve CAPTCHAs, and navigate as real users. Traditional defenses often fail to meet expectations or frustrate genuine users.

That’s why Vercel created BotID, an invisible CAPTCHA that has real-time protections against sophisticated bots that help you protect your critical endpoints.

In this blog post, we will explore why you should care about this new tool, how to set it up, its use cases, and some key considerations to take into account.

We will be using Next.js for our examples, but please note that this tool is not tied to this framework alone; the only requirement is that your app is deployed and running on Vercel.

Why Should You Care?

Think about these scenarios:

• Checkout flows are overwhelmed by scalpers
• Signup forms inundated with fake registrations
• API endpoints draining resources with malicious requests

They all impact you and your users in a negative way. For example, when bots flood your checkout page, real customers are unable to complete their purchases, resulting in your business losing money and damaging customer trust.

Fake signups clutter the app, slowing things down and making user data unreliable. When someone deliberately overloads your app’s API, it can crash or become unusable, making users angry and creating a significant issue for you, the owner.

BotID automatically detects and filters bots attempting to perform any of the above actions without interfering with real users.

How does it work? A lightweight first-party script quickly gathers a high set of browser & environment signals (this takes ~30ms, really fast so no worry about performance issues), packages them into an opaque token, and sends that token with protected requests via the rewritten challenge/proxy path + header; Vercel’s edge scores it, attaches a verdict, and checkBotId() function simply reads that verdict so your code can allow or block. We will see how this is implemented in a second! But first, let’s get started.

Getting Started in Minutes

1. Install the SDK:

npm install botid

1. Configure redirects

Wrap your next.config.ts with BotID’s helper. This sets up the right rewrites so BotID can do its job (and not get blocked by ad blockers, extensions, etc.):

import { withBotId } from 'botid/next/config';

const nextConfig = {
  // Your existing Next.js config
};

export default withBotId(nextConfig);

2. Integrate the client on public-facing pages (where BotID runs checks):

Declare which routes are protected so BotID can attach special headers when a real user triggers those routes.

We need to create instrumentation-client.ts (place it in the root of your application or inside a src folder) and initialize BotID once:

import { initBotId } from 'botid/client/core';

// Define the paths that need bot protection.
// These are paths that are routed to by your app.
// These can be:
// - API endpoints (e.g., '/api/checkout')
// - Server actions invoked from a page (e.g., '/dashboard')
// - Dynamic routes (e.g., '/api/create/*')

initBotId({
  protect: [
    {
      path: '/api/checkout',
      method: 'POST',
    },
    {
      // Wildcards can be used to expand multiple segments
      // /team/*/activate will match
      // /team/a/activate
      // /team/a/b/activate
      // /team/a/b/c/activate
      // ...
      path: '/team/*/activate',
      method: 'POST',
    },
    {
      // Wildcards can also be used at the end for dynamic routes
      path: '/api/user/*',
      method: 'POST',
    },
  ],
});

instrumentation-client.ts runs before the app hydrates, so it’s a perfect place for a global setup!

If we have an inferior Next.js version than 15.3, then we would need to use a different approach. We need to render the React component inside the pages or layouts you want to protect, specifying the protected routes:

import { BotIdClient } from 'botid/client';
import { ReactNode } from 'react';

const protectedRoutes = [
  {
    path: '/api/checkout',
    method: 'POST',
  },
];

type RootLayoutProps = {
  children: ReactNode;
};

export default function RootLayout({ children }: RootLayoutProps) {
  return (
    <html lang="en">
      <head>
        <BotIdClient protect={protectedRoutes} />
      </head>
      <body>{children}</body>
    </html>
  );
}

3. Verify requests on your server or API:

import { checkBotId } from 'botid/server';

export async function POST(req: Request) {
  const { isBot } = await checkBotId();

  if (isBot) {
   return new Response("Access Denied", { status: 403 });
  } 

  return new Response("✅ Success!");
}

• NOTE: checkBotId() will fail if the route wasn’t listed on the client, because the client is what attaches the special headers that let the edge classify the request!

You’re all set - your routes are now protected!

In development, checkBotId() function will always return isBot = false so you can build without friction. To disable this, you can override the options for development:

const { isBot } = await checkBotId({
    developmentOptions: {
      bypass: 'BAD-BOT', // default: 'HUMAN'
    },
  });

What happens on a failed check?

In our example above, if the check failed, we return a 403, but it is mostly up to you what to do in this case; the most common approaches for this scenario are:

• Hard block with a 403 for obviously automated traffic (just what we did in the example above)
• Soft fail (generic error/“try again”) when you want to be cautious.
• Step-up (require login, email verification, or other business logic).

Remember, although rare, false positives can occur, so it’s up to you to determine how you want to balance your fail strategy between security, UX, telemetry, and attacker behavior.

checkBotId()

So far, we have seen how to use the property isBot from checkBotId(), but there are a few more properties that you can leverage from it. There are:

isHuman (boolean): true when BotID classifies the request as a real human session (i.e., a clear “pass”). BotID is designed to return an unambiguous yes/no, so you can gate actions easily.

isBot (boolean): We already saw this one. It will be true when the request is classified as automated traffic.

isVerifiedBot (boolean): Here comes a less obvious property. Vercel maintains and continuously updates a comprehensive directory of known legitimate bots from across the internet. This directory is regularly updated to include new legitimate services as they emerge. This could be helpful for allowlists or custom logic per bot. We will see an example in a sec.

verifiedBotName? (string): The name for the specific verified bot (e.g., “claude-user”).

verifiedBotCategory? (string): The type of the verified bot (e.g., “webhook”, “advertising”, “ai_assistant”).

bypassed (boolean): it is true if the request skipped BotID check due to a configured Firewall bypass (custom or system). You could use this flag to avoid taking bot-based actions when you’ve explicitly bypassed protection.

Handling Verified Bots

• NOTE: Handling verified bots is available in botid@1.5.0 and above.

It might be the case that you don’t want to block some verified bots because they are not causing damage to you or your users, as it can sometimes be the case for AI-related bots that fetch your site to give information to a user.

We can use the properties related to verified bots from checkBotId() to handle these scenarios:

import { checkBotId } from "botid/server";
import { NextResponse } from "next/server";

export async function POST(request: Request) {
  const botResult = await checkBotId();

  const { isBot, verifiedBotName, isVerifiedBot } = botResult;

  // Check if it's ChatGPT Operator
  const isOperator = isVerifiedBot && verifiedBotName === "chatgpt-operator";

  if (isBot && !isOperator) {
    return Response.json({ error: "Access denied" }, { status: 403 });
  }

  // ... rest of your handler
  return Response.json(botResult);
} 

Choosing your BotID mode

When leveraging BotID, you can choose between 2 modes:

• Basic Mode: Instant session-based protection, available for all Vercel plans.
• Deep Analysis Mode: Enhanced Kasada-powered detection, only available for Pro and Enterprise plan users. Using this mode, you will leverage a more advanced detection and will block the hardest to catch bots

To specify the mode you want, you must do so in both the client and the server. This is important because if either of the two does not match, the verification will fail!

// Client side
initBotId({
  protect: [
    {
      path: '/api/checkout',
      method: 'POST',
      advancedOptions: {
        checkLevel: 'deepAnalysis'
      },
    },
 ...
  ],
});

// Server side
export async function POST(request: NextRequest) {
  const verification = await checkBotId({
    advancedOptions: {
      checkLevel: 'deepAnalysis', // Must match client-side config
    },
  });

  if (verification.isBot) {
    return NextResponse.json({ error: 'Access denied' }, { status: 403 });
  }

  // Your protected logic here
}

Conclusion

Stop chasing bots - let BotID handle them for you! Bots are and will get smarter and more sophisticated. BotID gives you a simple way to push back without slowing your customers down. It is simple to install, customize, and use.

Stronger protection equals fewer headaches. Add BotID, ship with confidence, and let the bots trample into a wall without knowing what’s going on.