SilentShield sicher in Ihr Formular integrieren

Client-Skript, serverseitige Prüfung, Schlüssel und Fehlerfälle – der vollständige Einbau an einer Stelle.

So arbeiten Skript und Serverprüfung zusammen

Ein vollständiger Einbau hat zwei Hälften: das Skript im Browser und eine Prüfung auf Ihrem Server.

1
Skript lädt
Ihre Seite lädt client.js?k=… mit Ihrem Website-Schlüssel. Das Skript misst das Verhalten im Formular.
2
Formular wird gesendet
Beim Absenden meldet das Skript die Messung und legt das Feld behavior_nonce in Ihr Formular.
3
Ihr Server fragt nach
Ihr Server schickt behavior_nonce an POST /api/v1/captcha/verify-nonce, mit Ihrem Schlüssel im Header X-Api-Key.
4
Sie entscheiden
Die Antwort enthält ok, verdict, confidence und reason_codes. Bei ok: true nehmen Sie die Absendung an, sonst lehnen Sie ab.

Ohne Schritt 3 schützt der Einbau nur halb: Das Skript allein hält keine Anfrage auf, die direkt an Ihren Server gesendet wird.

Website-Schlüssel und Serverschlüssel

Website-Schlüssel (öffentlich)

client.js?k=…

Steht im Quelltext Ihrer Seite und ist damit für jeden sichtbar. Er bindet das Skript an Ihre Domain; Subdomains wie www. oder staging. gehören dazu.

Serverschlüssel (geheim, optional)

X-Api-Key

Optional. Wenn Sie möchten, dass die Aufrufe Ihres Servers einen Wert tragen, der nicht im Quelltext Ihrer Seite steht, erzeugen Sie ihn im Dashboard beim Schlüssel im Reiter „Serverschlüssel“. Er gehört nur auf Ihren Server, nie in den Browser, und lässt sich jederzeit neu erzeugen.

Die Serverprüfung funktioniert allein mit dem Website-Schlüssel, Sie müssen also nichts ändern. Beide Schlüssel werden angenommen. Mit dem Serverschlüssel steht in Ihrem Servercode kein Wert, den jeder im Quelltext Ihrer Seite lesen kann.

Schnellstart

Installieren & Einbetten

Fügen Sie das Skript hinzu und erhalten Sie ein Token

Auf dem Server verifizieren

Validieren Sie das Token in Ihrem Backend

Schnelltest mit cURL

Token über die Kommandozeile verifizieren

# Nonce verifizieren
curl -X POST https://api.silentshield.io/api/v1/captcha/verify-nonce \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nonce": "256ea6c63c3ccdd317e05cbc9ef0c659"}'

Frontend Integration

Add the client script with SRI and defer attributes

<!-- In <head> or before </body> of every page with a form -->
<script src="https://api.silentshield.io/client.js?k=YOUR_API_KEY" defer></script>

Sicherheit & Datenschutz

Keine Cookies – vollständig ohne Cookies
Keine Profile, keine Cookies – DSGVO-konform einsetzbar
EU-Hosting – Prüfung und Speicherung auf unseren Servern in Deutschland
WCAG-konform – für alle Benutzer zugänglich
CSP-kompatibel – Verwendung mit Content Security Policy:

Content-Security-Policy: script-src 'self' https://api-us.silentshield.io https://api-eu.silentshield.io; connect-src 'self' https://api-us.silentshield.io https://api-eu.silentshield.io; worker-src 'self' blob:;

SDKs & Bibliotheken

Das Paket läuft auf Ihrem Server (Node.js ab 18). Im Browser brauchen Sie gar kein Paket — dort genügt das client.js-Snippet aus dem Schnellstart.

Node.js / Express

v1.5.0

npm i @forge12interactive/silentshield-sdk-js

import { createClient } from "@forge12interactive/silentshield-sdk-js";

const shield = createClient({ apiKey: process.env.SILENTSHIELD_API_KEY });

app.post("/signup", async (req, res) => {
  const { human } = await shield.verify(req.body.behavior_nonce);
  if (!human) return res.status(403).send("Verification failed");
  res.send("ok");
});

NPM

KI-Agenten (Node.js)

v1.5.0

npm i @forge12interactive/silentshield-sdk-js

import { createClient, enforce } from "@forge12interactive/silentshield-sdk-js";

const shield = createClient({ apiKey: process.env.SILENTSHIELD_API_KEY });

// Reports bot candidates only — never blocks, never sees human traffic.
app.use(shield.observe);

// Applies your policy locally from a signed bundle. Fail-open.
app.use(enforce({ apiKey: process.env.SILENTSHIELD_API_KEY }));

NPM

API-Referenz

API Version: 2025-10-01 · Base URL: https://api.silentshield.io

POST/api/v1/captcha/verify-nonce

SilentShield-Nonce verifizieren

Request Headers:

X-Api-KeyYOUR_API_KEY

Content-Typeapplication/json

Request Body:

noncestringDas zu verifizierende Nonce

Response:

Success (200):

{
  "ok": true,
  "verdict": "human",
  "confidence": 0.95,
  "requested_nonce": "256ea6c63c3ccdd317e05cbc9ef0c659"
}

Error:

{
  "ok": false,
  "verdict": "bot",
  "confidence": 0.12,
  "request_nonce": "256ea6c63c3ccdd317e05cbc9ef0c659",
  "reason_codes": ["NO_MOUSE_MOVEMENT"]
}

Status Codes:

200Nonce erfolgreich verifiziert

400Ungültige Anfrage (fehlendes oder fehlerhaftes Nonce)

401Ungültiger API-Schlüssel

403Nicht als Mensch bestätigt (ok: false) – Absendung ablehnen

429Rate-Limit überschritten

500Interner Server-Fehler

Zeitlimits, Ausfälle und Kontingent

Setzen Sie für die Serverprüfung ein Zeitlimit. Unsere Codebeispiele verwenden 5 Sekunden.
Antwortet die Prüfung nicht rechtzeitig, werten die Beispiele das als „nicht bestätigt“ und lehnen ab. Wenn Sie in diesem Fall lieber annehmen, fangen Sie den Fehler selbst ab — die Entscheidung liegt bei Ihnen.
Antwortet der erste Host nicht, während das Skript seine Einstellungen und Bausteine nachlädt, weicht es auf den zweiten aus (api.silentshield.io und api-eu.silentshield.io). Schlüssel mit strikter EU-Bindung bleiben auf dem EU-Host.
Für die Serverprüfung gibt es keinen automatischen Ausweichhost.
Über Ihrem Monatskontingent prüft die API weiter und antwortet wie gewohnt. Ein 429 bedeutet, dass das Rate-Limit pro Minute für Ihren Schlüssel überschritten ist.

Lokal und auf einer Testdomain prüfen

Auf localhost funktioniert Ihr Schlüssel nicht: Er ist an Ihre Domain gebunden, und das Skript wird dort abgewiesen.
Testen Sie auf einer Subdomain Ihrer Domain, zum Beispiel staging.ihre-domain.de. Sie läuft mit dem Schlüssel der Hauptdomain und belegt keinen weiteren Domain-Platz.
Möchten Sie Test und Live getrennt auswerten, legen Sie für dieselbe Domain einen zweiten Schlüssel an. Auch er belegt keinen weiteren Domain-Platz.
Senden Sie zum Test ein Formular ab und prüfen Sie auf Ihrem Server die Antwort von verify-nonce: Bei einer Eingabe von Hand sollte ok: true zurückkommen; sonst zeigen die reason_codes, warum nicht.

Testdomain einrichten

Versionen und Änderungen

Die API trägt ihre Version im Pfad: /api/v1. Unter /api liegen dieselben Routen.
Das Skript hat keine Versionsnummer: client.js liefert immer die aktuelle Fassung, Sie müssen nichts aktualisieren.
Die SDKs für PHP, Node, Go und Edge haben Versionsnummern; Änderungen stehen im Changelog des jeweiligen Pakets.
Änderungen an API und Skript veröffentlichen wir im Changelog.

Ressourcen

Hilfe-Center

Umfassende Dokumentation mit Erste-Schritte-Anleitungen, Integrations-Tutorials, Konfigurations-Referenzen und Fehlerbehebung.

Hilfe-Center öffnen

Änderungsprotokoll

Bleiben Sie auf dem Laufenden über die neuesten Features, Verbesserungen und Fixes.

Changelog anzeigen

Bereit zum Start?

Erstellen Sie ein kostenloses Konto und erhalten Sie Ihren Schlüssel.

Jetzt starten