API Turnstile (Sentinel) — Turnstile for APIs

Your APIs are being abused. You just don't see it yet.

Cloudflare Turnstile protects browsers. Sentinel protects APIs.

---

Sentinel is a high-velocity deterministic trust layer for modern APIs. It stops automated abuse, credential stuffing, and fake signups by analyzing Infrastructure DNA and enforcing Behavioral Work Tokens without ever showing a CAPTCHA to a human.

🚫 Problems We Stop

• Signup Flooding: Thousands of fake accounts hitting your database.
• Credential Stuffing: Automated login attempts using leaked passwords.
• API Scraping: Competitors or AI agents draining your proprietary data.
• Ghost Traffic Tax: Unnecessary AWS/Cloud compute costs from non-human traffic.

⚡ Global Edge Enforcement

Sentinel is built for the internet's edge. Deploy as a standard Node.js middleware or a Global Edge Guard on Cloudflare Workers / Vercel Edge.

• Fast-Path Matrix: Instant identification of hosting/proxy infrastructure.
• Edge Cache Support: Sub-2ms rejection using Cloudflare KV or Vercel Edge Config.
• Agentic Governance: Specific profiles to identify and throttle AI Agents vs Humans.

Example: Cloudflare Worker Edge Enforcement

import { sentinelEdge } from 'api-turnstile';

export default {
  async fetch(request, env, ctx) {
    const shield = sentinelEdge({
      apiKey: env.SENTINEL_KEY,
      cache: env.SENTINEL_KV, // Cloudflare KV Namespace
      protect: ['/v1/*'],
      profile: 'agentic' // Identify & throttle AI Agents
    });

    const blockResponse = await shield(request, ctx);
    if (blockResponse) return blockResponse;

    return await fetch(request);
  }
};

---

Key Features

• Extreme Performance: Sub-50ms decision latency globally.
• Zero Friction: No CAPTCHAs, no puzzles, no interrupted user flows.
• Adaptive Defenses: Automatically scales security based on the risk-score of an incoming request.
• Framework Agnostic: Native middleware for Express, Fastify, Next.js, Hono, and Bun.
• CLI Forensics: Stream live traffic decisions and audit IPs directly from your terminal.
• Outcome-Focused: Designed for Registration Fraud, Account Takeover (ATO), and Scraping Prevention.

---

Installation

npm install api-turnstile

---

Basic Integration

Express.js

import { sentinel } from 'api-turnstile';
import express from 'express';

const app = express();

app.use(sentinel({
  apiKey: 'YOUR_SENTINEL_KEY',
  protect: ['/api/auth/*', '/v1/payments'],
  profile: 'api' // Default profile
}));

Next.js (Edge Middleware)

// middleware.ts
import { sentinelEdge } from 'api-turnstile';

export default sentinelEdge({
  apiKey: process.env.SENTINEL_KEY,
  protect: {
    '/api/auth/*': 'strict',
    '/api/public/*': 'monitor'
  }
});

export const config = {
  matcher: '/api/:path*',
};

---

Advanced Configuration

The sentinel middleware accepts a SentinelConfig object for granular control.

Option	Type	Default	Description
apiKey	string	Required	Your Sentinel API key.
protect	string[] | Object	[]	List of paths to protect or a map of path patterns to ProtectionMode.
profile	string	'api'	Sensitivity profile: api, signup, payments, crypto.
fail	'open' | 'closed'	'closed'	Fail strategy if API is unreachable. closed blocks access.
onBlock	Function	403 JSON	Custom block handler: (req, res, decision) => void.
bwt.enabled	boolean	true	Enable Behavioral Work Tokens (Adaptive PoW).
webhooks.onBlock	string	undefined	URL to POST to when an attack is blocked.

Path Protection Modes

Control how strictly each path is enforced:

• monitor: Passive logging. Never blocks.
• balanced: Defensive mode. Blocks high-confidence automated threats.
• strict: Zero-tolerance. Blocks any suspicious signal including VPNs and Datacenters.

protect: {
  '/api/public': 'monitor',
  '/api/user/*': 'balanced',
  '/api/sensitive': 'strict'
}

---

Security Profiles

Sentinel profiles tune the engine's heuristics based on the endpoint's value:

Profile	Focus	Use Case
api	Velocity	Standard API endpoints, data feeds.
signup	Identity	Registration, Login, Forget Password.
payments	Integrity	Checkout, Subscription, Payment Method Update.
crypto	Pure Trust	Wallets, Faucets, On-Chain interactions.
agentic	AI Governance	LLM Agents, Scrapers, Automated Crawlers.

Using the Agentic Profile

The agentic profile is designed to differentiate between human users and AI Agents (like GPT-5, Perplexity, etc.). When enabled, Sentinel provides granular signals that allow you to serve "Lite" or "Cached" content to bots while saving expensive compute for humans.

app.use(sentinel({
  apiKey: '...',
  protect: ['/data/*'],
  profile: 'agentic'
}));

---

Response Formats

Successful Decision (Allowed)

Requests that pass Sentinel checks proceed seamlessly to your next middleware.

Blocked Decision (Default 403)

If a request is blocked, Sentinel returns a detailed forensic response:

{
  "error": "Access denied",
  "reason": "Headless browser signature detected (Puppeteer/Chrome)",
  "remediation": {
    "widget_required": false,
    "trust_token_eligible": true
  }
}

---

Sentinel CLI

The package includes a powerful command-line interface for real-time traffic analysis.

# Install CLI globally
npm install -g api-turnstile

# Stream live traffic forensic decisions
sentinel tail --key YOUR_API_KEY

# Perform an immediate audit on an IP address
sentinel check 1.2.3.4

# View security ROI and outcome metrics
sentinel stats

---

Behavioral Work Tokens (BWT)

BWT is our proprietary adaptive PoW system. When Sentinel identifies an "Unstable" IP, it scales a cryptographic challenge that must be solved by the client.

1. Legitimate Users: The api-turnstile client (or frontend widget) solves the challenge in ~10-40ms in the background.
2. Bot Scripts: Python, Go, and simple NodeJS scripts fail the challenge as they lack the cryptographic engine required to generate a valid BWT-Nonce.

---

Deployment & Compatibility

• Node.js: 18.x and above.
• Bun: 1.0.0 and above.
• Cloud Runtime: Vercel Edge, Cloudflare Workers, AWS Lambda.
• Database: Zero external DB dependencies (Decision Engine is managed).

Related

• Sentinel API Security Platform — Managed API bot protection
• Why CAPTCHAs Fail for APIs

License

MIT © Sentinel Security