SilentShield

Widget-Endpunkte

Diese Endpunkte ruft das SilentShield-Widget auf. Normalerweise müssen Sie das nicht selbst tun — hier stehen sie, damit Sie nachvollziehen können, was auf Ihrer Seite passiert.

Base URL: https://api.silentshield.io

POST/api/v1/telemetry/behavior

Sendet die Verhaltensdaten der aktuellen Interaktion (Maus, Tastatur, Scrollen) und bekommt die Nonce samt Bewertung zurück. Diese Nonce reicht Ihr Formular mit — als Feld `behavior_nonce`.

Auth: API-Key (X-Api-Key Header)

Request Body:

{"ts": 1767225600000, "nonce": "bh_abc123", "event": "submit", "form_key": "contact", "feature_hash": "...", "metrics": {...}, "signature": "..."}

Response:

{"id": "...", "nonce": "bh_abc123", "status": "queued", "verdict": "human", "score": 0.87, "captcha_solved": false, "challenge_required": false, "difficulty": "pass", "reason_codes": [], "action": "allow"}

Zählt zu Ihrem Kontingent, sobald das Ereignis `submit` mit einer Nonce ankommt — also genau einmal je Absendung. `init`, `telemetry` und `form_detected` zählen nicht.

POST/api/v1/captcha/challenge

Fordert eine Rechenaufgabe an, wenn die Bewertung unsicher war. Das Widget tut das von sich aus; die Aufgabe ist einmalig und an die Nonce gebunden.

Auth: API-Key (X-Api-Key Header)

Request Body:

{"nonce": "bh_abc123", "difficulty": "medium"}

Response:

{"ok": true, "challenge_id": "ch_xyz789", "a": 7, "op": "+", "b": 5}

Nur nötig, wenn die Telemetrie-Antwort `challenge_required: true` gemeldet hat.

POST/api/v1/captcha/verified

Reicht die gelöste Aufgabe ein. Erst wenn die Antwort zu einer Aufgabe passt, die der Server für diesen Schlüssel ausgegeben hat, wird die Nonce als menschlich markiert.

Auth: API-Key (X-Api-Key Header)

Request Body:

{"challenge_id": "ch_xyz789", "answer": 12}

Response:

{"ok": true}   //  403: {"ok": false, "reason": "invalid_solution"}

Fail-closed: Eine falsche oder abgelaufene Antwort ergibt 403 mit `reason: "invalid_solution"`. Die Aufgabe ist einmalig.

POST/api/v1/captcha/verify-nonce

Verifiziert eine vom Widget generierte Nonce. Rufen Sie dies von Ihrem Server auf, um die Formularübermittlung als legitim zu bestätigen.

Auth: API-Key (X-Api-Key Header)

Request Body:

{"nonce": "nonce_xyz789"}

Response:

{"valid": true, "verdict": "human", "score": 0.92, "timestamp": "2025-01-15T10:30:00Z"}

Dieser Endpunkt zählt zu Ihrem Kontingent. Nonces sind einmalig verwendbar und laufen nach 5 Minuten ab.