SilentShield

Endpoints du widget

Ces points de terminaison sont appelés par le widget SilentShield. Vous ne les appelez normalement pas vous-même : ils sont documentés pour que vous puissiez suivre ce qui se passe sur votre page.

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

POST/api/v1/telemetry/behavior

Envoie les données comportementales de l’interaction en cours (souris, clavier, défilement) et renvoie le nonce accompagné d’un verdict. Votre formulaire transmet ce nonce dans le champ `behavior_nonce`.

Auth: API Key (en-tête X-Api-Key)

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"}

Compte dans votre quota dès que l’événement `submit` arrive avec un nonce — exactement une fois par envoi. `init`, `telemetry` et `form_detected` ne comptent pas.

POST/api/v1/captcha/challenge

Demande un calcul à résoudre lorsque le verdict était incertain. Le widget le fait de lui-même ; l’épreuve est à usage unique et liée au nonce.

Auth: API Key (en-tête X-Api-Key)

Request Body:

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

Response:

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

Nécessaire uniquement lorsque la réponse de télémétrie a indiqué `challenge_required: true`.

POST/api/v1/captcha/verified

Soumet l’épreuve résolue. Le nonce n’est marqué comme humain que si la réponse correspond à une épreuve émise par le serveur pour cette clé.

Auth: API Key (en-tête X-Api-Key)

Request Body:

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

Response:

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

Fail-closed : une réponse fausse ou expirée renvoie 403 avec `reason: "invalid_solution"`. L’épreuve est à usage unique.

POST/api/v1/captcha/verify-nonce

Vérifie un nonce généré par le widget. Appelez ce endpoint depuis votre serveur pour confirmer que la soumission du formulaire est légitime.

Auth: API Key (en-tête X-Api-Key)

Request Body:

{"nonce": "nonce_xyz789"}

Response:

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

Ce endpoint compte dans votre quota. Les nonces sont à usage unique et expirent après 5 minutes.