# Deploying and testing BotID **Author:** Liz Hurder, Andrew Qu --- ## 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 ## 1\. Prerequisites Before you begin: - You have a Vercel account and an existing project (or you can start from the [Next.js starter template](https://vercel.com/templates/edge-middleware/bot-protection-botd)). - You can deploy to Vercel via Git or by clicking **Deploy** on a template. ## 2\. Configure Redirects 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);` ## 3\. Install the BotID SDK 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. ## 4\. Add the BotID Client 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 ( {children} ); }` For improved performance in Next.js 15.3+, we recommend using initBotId() in instrumentation-client.ts. If you’re on an earlier version, continue using the React component approach shown above. This ensures every page initializes the BotID client in the browser. ## 5\. Verify Requests on the Server 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. ## 6\. Allow Trusted Automation (Optional) 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. ## 7\. Add WAF and Rate Limiting (Optional) For extra protection, layer [**Vercel WAF**](https://vercel.com/docs/vercel-firewall/vercel-waf/rate-limiting-sdk) 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. ## 8\. Test Locally Run your app locally to confirm setup: `npm run dev` 1. Open [http://localhost:3000](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. ## 9\. Deploy to Vercel 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** ## 10\. Validate in Production Perform a quick verification: | Scenario | Expected Result | | -------------------------- | ---------------- | | Normal browser visit | Request allowed | | Headless `curl` or script | Request blocked | | Allowed crawler or webhook | Request verified | Monitor logs and analytics for any blocked requests. Adjust WAF rules or allowlists as needed. ## 11\. Troubleshooting | Issue | Fix | | --------------------------------- | -------------------------------------------------------------------------------------------------- | | All requests are allowed | Confirm `` 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. | --- [View full KB sitemap](/kb/sitemap.md)