Advanced BotID Configuration

When you need fine-grained control over BotID's detection levels, you can specify advancedOptions to choose between basic and deep analysis modes on a per-route basis. This configuration takes precedence over the project-level BotID settings in your Vercel dashboard.

In your client-side protection setup, you can specify the check level for each protected path:

initBotId({
  protect: [
    {
      path: '/api/checkout',
      method: 'POST',
      advancedOptions: {
        checkLevel: 'deepAnalysis', // or 'basic'
      },
    },
    {
      path: '/api/contact',
      method: 'POST',
      advancedOptions: {
        checkLevel: 'basic',
      },
    },
  ],
});

In your server-side endpoint that uses checkBotId(), ensure it matches the client-side configuration.

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
}

By default, BotID validates that requests come from the same host that serves the BotID challenge. However, if your application architecture separates your frontend and backend domains (e.g., your app is served from vercel.com but your API is on api.vercel.com or vercel-api.com), you'll need to configure extraAllowedHosts.

The extraAllowedHosts parameter in checkBotId() allows you to specify a list of frontend domains that are permitted to send requests to your backend:

export async function POST(request: NextRequest) {
  const verification = await checkBotId({
    advancedOptions: {
      extraAllowedHosts: ['vercel.com', 'app.vercel.com'],
    },
  });
 
  if (verification.isBot) {
    return NextResponse.json({ error: 'Access denied' }, { status: 403 });
  }
 
  // Your protected logic here
}

Use this configuration when:

• Your frontend is hosted on a different domain than your API (e.g., myapp.com → api.myapp.com)
• You have multiple frontend applications that need to access the same protected backend
• Your architecture uses a separate subdomain for API endpoints

You can combine extraAllowedHosts with other advanced options:

const verification = await checkBotId({
  advancedOptions: {
    checkLevel: 'deepAnalysis',
    extraAllowedHosts: ['app.example.com', 'dashboard.example.com'],
  },
});