Betrieb

Verhalten bei Ausfall, Schlüsselrotation, Server-Beispiele, Domains und Content Security Policy.

Auf dieser Seite

Fehlerbehandlung & Fail-Open Schlüssel & Rotation Backend-Beispiele Domains, CORS & CSP

Fehlerbehandlung & Fail-Open

Wenn der CaptchaCore-Service nicht erreichbar ist, kann das Verhalten konfiguriert werden:

Fail-Open (Standard)

Formulare werden trotzdem durchgelassen. Verfügbarkeit > Sicherheit bei Ausfall. Empfohlen für die meisten Sites.

CAPTCHACORE_FAIL_OPEN=true

Fail-Closed

Formulare werden blockiert wenn der Service nicht antwortet. Nur für hochkritische Systeme.

CAPTCHACORE_FAIL_OPEN=false

Alle API-Calls haben einen Timeout von 3 Sekunden. Bei Timeout greift die Fail-Open/Closed-Konfiguration.

Keys & Rotation

Jede Site hat ein Key-Paar: Site Key (public, im Browser) und Secret Key (geheim, nur Server).

Key-Formate

cc_pub_6e65b5c4597a688c93f3be6e345ee1a5...  ← 7 + 64 hex = 71 Zeichen
cc_sec_8bb043aa6424a1fdb3e048d2d3232894...  ← 7 + 64 hex = 71 Zeichen

Key-Rotation

Bei Rotation wird der alte Key in den Status rotated versetzt und bleibt noch 24 Stunden gültig. So können Rolling Deployments ohne Downtime durchgeführt werden.

active — aktueller Key, wird für neue Requests verwendet
rotated — alter Key, noch 24h gültig (konfigurierbar)
revoked — sofort ungültig, keine Requests mehr möglich

Secret Key Sicherheit

  • Secret Key wird als SHA-256 Hash in der Datenbank gespeichert
  • Klartext wird nur einmalig nach Erstellung angezeigt
  • Kann nicht wiederhergestellt werden — bei Verlust: neuen Key generieren
  • Wird niemals in Logs, API-Responses oder Fehlermeldungen ausgegeben

Backend-Beispiele

Der Verify-Endpoint kann von jedem Backend aufgerufen werden. Hier Beispiele für gängige Sprachen:

PHP (ohne Framework)

$token = $_POST['captchacore_token'] ?? '';

$ch = curl_init('https://api.captchacore.eu/api/v2/verify');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 3,
    CURLOPT_HTTPHEADER     => [
        'X-CaptchaCore-Key: cc_sec_DEIN_SECRET',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'token'     => $token,
        'form_type' => 'contact',
    ]),
]);
$result = json_decode(curl_exec($ch), true);

if (!$result['valid']) {
    die('Bot erkannt.');
}

Node.js

const token = req.body.captchacore_token;

const res = await fetch('https://api.captchacore.eu/api/v2/verify', {
  method: 'POST',
  headers: {
    'X-CaptchaCore-Key': process.env.CAPTCHACORE_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ token, form_type: 'register' }),
});
const { valid, risk_score, action } = await res.json();

if (!valid) return res.status(403).json({ error: 'Bot detected' });

Python

import requests

result = requests.post(
    'https://api.captchacore.eu/api/v2/verify',
    headers={'X-CaptchaCore-Key': 'cc_sec_DEIN_SECRET'},
    json={'token': token, 'form_type': 'login'},
    timeout=3,
).json()

if not result['valid']:
    raise Exception('CaptchaCore verification failed')

Infrastruktur & Domains

Domain-Architektur

Domain Zweck Typ
api.captchacore.euChallenge, Verify, Status, VersionAPI (JSON)
src-eu.captchacore.euWidget JS + Worker (EU-only CDN)CDN (Standard)
src.captchacore.euWidget JS + Worker (Globales CDN)CDN (optional)
captchacore.euWebsite, Admin-Panel, DocsFrontend

Content Security Policy (CSP)

Wenn Sie auf Ihrer Website eine Content Security Policy verwenden, müssen folgende Domains erlaubt werden:

# Minimal (EU-only CDN + API)
script-src  https://src-eu.captchacore.eu;
connect-src https://api.captchacore.eu https://src-eu.captchacore.eu;
worker-src  blob:;

# Mit globalem CDN (zusätzlich)
script-src  https://src.captchacore.eu;
connect-src https://src.captchacore.eu;

Warum diese Einträge?

  • script-src — Das Widget-JS (captchacore-v2.min.js) wird vom CDN geladen
  • connect-src (API) — Das Widget ruft /api/v2/challenge per fetch() auf
  • connect-src (CDN) — Der PoW-Worker wird per fetch() vom CDN nachgeladen
  • worker-src blob: — Der Worker wird als Blob-URL instanziiert (vermeidet CORS)

CORS-Header

CaptchaCore setzt automatisch die richtigen CORS-Header auf allen API-Endpoints. Sie müssen auf Ihrer Seite keine CORS-Konfiguration vornehmen. Die API antwortet mit:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Accept, X-CaptchaCore-Key

NGINX-Beispiel für Ihre Webseite

Falls Sie eine strenge CSP auf Ihrer Webseite konfiguriert haben:

# NGINX — CSP für CaptchaCore Widget
add_header Content-Security-Policy
  "script-src 'self' https://src-eu.captchacore.eu;
   connect-src 'self' https://api.captchacore.eu https://src-eu.captchacore.eu;
   worker-src 'self' blob:;"

Zurück

Erkennung

Weiter

Hilfe & Datenschutz