API Turnstile (Sentinel) — Turnstile for 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.

$3

``typescript
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

`bash
npm install api-turnstile
`

---

Basic Integration

$3

`javascript
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
}));
`

$3

`typescript
// 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. |

$3

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.

`javascript
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. |

$3

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.

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

---

Response Formats

$3

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

$3

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

`json
{
"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.

`bash

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