Quick Start

Get up and running in under a minute.

<script src="https://forge.benegedeniz.com/widget/forge.js" async defer></script>

<form action="/submit" method="POST">
    <div class="forge-captcha" data-sitekey="YOUR_SITEKEY"></div>
    <button type="submit">Submit</button>
</form>

Client-Side

Automatic Rendering

The widget automatically renders on all elements with the forge-captcha class.

<div class="forge-captcha" data-sitekey="YOUR_SITEKEY"></div>

JavaScript API

For programmatic control, use the ForgeCaptcha global object.

// Programmatic rendering
const widgetId = ForgeCaptcha.render('#my-container', {
    sitekey: 'YOUR_SITEKEY',
    callback: function(token) {
        console.log('Verified:', token);
    },
    'error-callback': function() {
        console.log('Challenge failed');
    }
});

// Get the response token
const token = ForgeCaptcha.getResponse(widgetId);

// Reset the widget
ForgeCaptcha.reset(widgetId);

Data Attributes

Drop-In Replacement

BenEgeDeniz Forge acts as a 100% native drop-in replacement for other popular captcha services. If your system already uses one of the services below, you can switch simply by changing the script URL, without modifying your HTML elements or server validation variables.

Server-Side

After the widget generates a token, verify it on your server before processing the request.

PHP

$response = file_get_contents('https://forge.benegedeniz.com/api/siteverify', false,
    stream_context_create(['http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json',
        'content' => json_encode([
            'secret' => 'YOUR_SECRET_KEY',
            'response' => $_POST['forge-captcha-response'],
            'remoteip' => $_SERVER['REMOTE_ADDR'],
        ]),
    ]])
);

$result = json_decode($response, true);
if ($result['success']) {
    // User verified - process the form
}

Node.js

const res = await fetch('https://forge.benegedeniz.com/api/siteverify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        secret: process.env.FORGE_SECRET_KEY,
        response: req.body['forge-captcha-response'],
    }),
});

const data = await res.json();
if (data.success) {
    // User verified
}

cURL

curl -X POST https://forge.benegedeniz.com/api/siteverify \
  -H "Content-Type: application/json" \
  -d '{"secret":"YOUR_SECRET","response":"TOKEN_FROM_WIDGET"}'

API Reference

{ "sitekey": "your-site-uuid" }

{
    "success": true,
    "challenge_id": "uuid",
    "salt": "hex-string",
    "difficulty": 20,
    "algorithm": "SHA-256",
    "expires_at": "2025-01-01T00:00:00Z"
}

{
    "secret": "your-secret-key",
    "response": "token-from-widget",
    "remoteip": "optional-client-ip"
}

{
    "success": true,
    "challenge_ts": "2025-01-01T00:00:00+00:00",
    "hostname": "example.com",
    "difficulty": 20,
    "is_interactive": true
}

Configuration

Configure your site's difficulty level in the dashboard.

Page Rules

Page Rules allow you to define custom verification behaviors (Difficulty Level, Invisible Mode, Hands-Free Auto Verify) for different pages or URL patterns on your site.

Match Types

Rule Evaluation

Rules are evaluated in the order of priority (top to bottom) that you set in your dashboard. The first rule that matches the visited URL is applied. If no rules match, the site's general settings take effect.

Advanced Security & Threat Intelligence

BenEgeDeniz Forge employs dynamic threat intelligence to protect your forms against advanced bots and headless browsers.

Trust Scores & Telemetry

The widget securely evaluates mouse movements, touch pressure variance, and keystrokes to calculate an "interaction entropy" score. Additionally, it collects passive environment signals (WebGL rendering profiles, device memory, webdriver flags). Automated scripts and headless browsers typically fail these checks, allowing Forge to silently penalize their trust score and exponentially increase the cryptographic difficulty.

Bot Protection Levels

You can configure the strictness of the security engine via Bot Protection Levels (Low, Medium, High). Higher levels enforce stricter trust score thresholds and immediately reject requests with suspicious IP or browser anomalies.

Mode-Aware Protection

The security engine is fully aware of your configuration. If a challenge is set to Invisible or Auto-Verify mode, active interaction penalties are intelligently disabled, ensuring legitimate users are not penalized. Instead, the system relies on strict passive environment signals, Challenge-IP binding, and PoW timing floors to catch bots.

Threat Logging

All blocked attacks, brute-force attempts, domain spoofing, IP mismatches, and PoW timing anomalies are recorded in real-time. You can monitor these metrics and inspect the raw metadata of each attack in the Security tab of your site dashboard.