Deploying and testing BotID

This guide gives an overview on Vercel BotID and how to deploy and test it in production

Avatar for lizhurder-1043Liz HurderSr. Product Marketing Manager
Avatar for quuuAndrew QuChief of Software, Vercel
Guides/BotID
3 min read
Last updated November 4, 2025

What is BotID

Vercel BotID adds invisible bot protection to your web application—no CAPTCHAs required. It analyzes request and browser signals in real time to detect and block automated traffic before it reaches costly or sensitive endpoints such as /api/generate or /api/checkout.

It comes in two tiers: Basic and Deep Analysis. The deployment process is identical for both, and the user can toggle to Deep Analysis mode through the UI or in the SDK.

  • BotID Basic (free): provides real-time, lightweight bot detection on each request using client and network signals.
  • Deep Analysis (paid): performs a deeper, asynchronous investigation of suspicious requests with additional telemetry and behavioral patterns.

What makes it different than Vercel’s Bot Manager?

BotID is client-side bot protection that focuses on detecting and blocking individual automated requests in real time.

Vercel’s Bot Manager is a managed ruleset that identifies known and verified bots (like search engines or uptime monitors) to allow legitimate automation through while providing visibility into overall bot traffic.

How does it work?

BotID adds a client script to your frontend that sets headers on requests to a protected endpoint. The server-side check uses those headers to classify the session. . The client gathers browser and behavioral signals, while the server verifies each request’s authenticity before running its detection logic. This process accurately determines automated behavior without interaction or CAPTCHAs.

What endpoints should I use it for?

Use BotID to protect high-cost, high-sensitivity routes, including:

  • AI or generative endpoints (e.g., /api/generate)
  • Checkout or payment APIs
  • Account creation or authentication routes
  • Rate-limited or metered API endpoints

Essentially, any endpoint where automated abuse could increase costs or degrade performance

Install & Deploy Vercel BotID

Before you begin:

  • You have a Vercel account and an existing project (or you can start from the Next.js starter template).
  • You can deploy to Vercel via Git or by clicking Deploy on a template.

Set up proxy rewrites ensures that ad-blockers, third party scripts, and more won't make BotID any less effective.

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


const nextConfig = {  


// Your existing Next.js config


}; 


export default withBotId(nextConfig);

From your project directory, install the BotID package

npm install botid 


# or 


yarn add botid

If you’re starting from the official BotID starter, the SDK is already included.

The client component collects browser signals needed for verification.

In a Next.js App Router project, open app/layout.tsx and add:

import { BotIdClient } from "botid/client"; 


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

This ensures every page initializes the BotID client in the browser.

On the server, use the checkBotId() helper to validate incoming requests before executing expensive logic.

Example – app/api/generate/route.ts:

import { checkBotId } from "botid/server"; 


export async function POST(req: Request) { 


const { isBot } = await checkBotId(); 


if (isBot) { 


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


} // Continue with your expensive or sensitive logic 


return new Response("Success", { status: 200 }); 


}

This combination—client signals + server verification—is the recommended pattern for securing AI, API, or checkout endpoints.

You can still allow legitimate automated services such as search-engine crawlers and webhooks.

Vercel’s Verified Bots feature automatically identifies these and lets you maintain access while blocking unwanted bots.

For extra protection, layer Vercel WAF rules on top of BotID.

This enables you to block, challenge, or rate-limit by IP, user agent, geo-region, or specific paths—helpful during scraping spikes or suspicious activity.

Run your app locally to confirm setup:

npm run dev
  1. Open http://localhost:3000.
  2. Trigger a protected route (e.g., click a button that calls /api/generate).
  3. In a normal browser, the request should succeed.
  4. In a headless request (curl or script), you should see Access Denied.

This confirms BotID is correctly distinguishing between real users and bots.

Push your changes to GitHub, GitLab, or Bitbucket—or click Deploy on the BotID starter template.

  • Use a Preview Deployment to validate BotID’s behavior.
  • Once validated, promote to Production

Perform a quick verification:

Scenario

Expected Result

Normal browser visit

Request allowed

Headless curl or script

Request blocked

Allowed crawler or webhook

Request allowed (Verified Bot)

Monitor logs and analytics for any blocked requests. Adjust WAF rules or allowlists as needed.

Issue

Fix

All requests are allowed

Confirm <BotIdClient /> is mounted and checkBotId() is called in your server route.

Legitimate traffic blocked

Verify allowlists and Verified Bots configuration. Relax overly strict WAF rules if necessary.

Headless test passes unexpectedly

Clear caches and ensure client + server packages are on the same version.

Was this helpful?

supported.