Skip to main content

​
Self-Hosted Gateway

For partners who want full control over their bot protection layer, BotShield provides an open-source gateway template that you deploy on your own infrastructure. Same verification flow, fully customizable.
The self-hosted gateway uses the same BotShield verification as the managed option. You still need an active BotShield account and gate credentials from your Partner Dashboard.

​
Why Self-Host?

The managed gateway is the fastest way to get protected — zero code, managed infrastructure. The self-hosted option is for teams that need:
NeedSelf-Hosted Advantage
Path-based rulesSkip verification for API routes, static assets, health checks, webhooks
Custom brandingMatch the verification page to your brand — colors, logo, copy
Your own infrastructureDeploy on your Cloudflare account, or port to Vercel Edge, Deno Deploy, Fastly Compute, AWS CloudFront Functions
Audit and complianceFull visibility into the proxy code — no hidden behavior, no data collection
Advanced routingRate limiting, geo-blocking, A/B testing, custom headers before or after verification

​
Get the Template

The gateway template is available on GitHub. Clone it, configure it, deploy it.

View on GitHub

Browse the source code, examples, and documentation

Download ZIP

Download the latest release as a ZIP archive

​
Quick Start

​
1. Clone the repository

git clone https://github.com/Bot-Shield/botshield-gate-public.git
cd botshield-gate-public
npm install

​
2. Get your credentials

From your Partner Dashboard, navigate to Storefront Gate and note your:
  • Gate ID — identifies your gate configuration
  • JWT Secret — the HS256 signing key for session tokens

​
3. Configure

Update wrangler.toml with your settings: 
[vars]
ORIGIN_HOST = "origin.yourstore.com"   # Your real server
GATE_ID = "gate_abc123"                # From your dashboard
Set the JWT secret (never commit this to source control): 
npx wrangler secret put BOTSHIELD_JWT_SECRET
# Paste the HS256 key from your dashboard

​
4. Create a KV namespace

The gateway caches configuration in Cloudflare KV: 
npx wrangler kv namespace create GATE_CACHE
Copy the returned id into wrangler.toml.

​
5. Deploy

npm run deploy
Point your domain’s DNS to the deployed worker (custom domain or worker route).

​
Customization

​
Skip verification for specific paths

The template includes an example for bypassing the gate on certain routes — useful for API endpoints, static assets, health checks, and webhooks. 
// examples/path-allowlist.ts

const ALLOWED_PATHS = [
  '/api/',          // Your API endpoints
  '/health',        // Health checks
  '/favicon.ico',
  '/robots.txt',
];

const ALLOWED_EXTENSIONS = [
  '.css', '.js', '.png', '.jpg', '.svg', '.woff2',
];

export function shouldBypass(url: URL): boolean {
  const path = url.pathname.toLowerCase();
  if (ALLOWED_PATHS.some(p => path === p || path.startsWith(p))) return true;
  if (ALLOWED_EXTENSIONS.some(ext => path.endsWith(ext))) return true;
  return false;
}
Import it in worker/index.ts and call shouldBypass(url) before the session check to proxy matching requests without verification.

​
Custom verification page

The verification page is a single function in worker/gateHtml.ts. Replace the HTML and CSS to match your brand: 
// worker/gateHtml.ts

export function renderGatePage(host: string, returnTo: string, gateId: string): string {
  const verifyUrl = `https://app.botshield.ai/verify?gate_id=${encodeURIComponent(gateId)}&...`;

  return `<!DOCTYPE html>
<html>
  <body>
    <!-- Your custom branded page here -->
    <h1>Verify to access ${host}</h1>
    <a href="${verifyUrl}">Verify Now</a>
  </body>
</html>`;
}
The only requirement is that the verify link points to the BotShield verify URL with the correct parameters. Everything else — layout, styling, copy, logo — is yours to customize. A complete branded example is included at examples/custom-branding.ts.

​
Platform Compatibility

The gateway template is built for Cloudflare Workers but uses only standard Web APIs (fetch, crypto.subtle, Request, Response). It can be adapted to run on any edge platform that supports these APIs:
PlatformCompatibilityNotes
Cloudflare WorkersReady to deployTemplate default — uses wrangler CLI
Vercel Edge FunctionsPortableReplace KV with Vercel KV or Edge Config
Deno DeployPortableNative Web API support, swap KV for Deno KV
Fastly ComputePortableRequires Fastly’s Wasm adapter for crypto.subtle
AWS CloudFront FunctionsPartialLimited crypto.subtle support — may need Lambda@Edge
The core logic (JWT verification, cookie handling, proxying) is ~200 lines of TypeScript with zero npm dependencies beyond dev tooling.

​
Architecture

Your edge worker handles everything. The only external dependency is the BotShield verification flow itself — when a visitor needs to verify, they’re directed to app.botshield.ai and redirected back with a signed token.

​
Security

The self-hosted gateway inherits the same security model as the managed option:
  • HS256 JWT validation — tokens are signed with your secret and verified using the Web Crypto API
  • HttpOnly, Secure cookies — session tokens can’t be accessed by client-side code
  • Header sanitization — internal headers and the gate cookie are stripped before proxying to your origin
  • No PII — no personal data is stored, logged, or transmitted
  • Open source — inspect every line of code that runs in front of your traffic

​
Next Steps

Managed Gateway

Prefer zero-config? Use the managed gateway instead.

GitHub Repository

Full source code, examples, and setup instructions.

SDK Overview

Build deeper integrations with the BotShield API.

Shopify Integration

Running Shopify? Use the native checkout extension.