Intégrer SilentShield de manière sécurisée dans votre formulaire

Script client, vérification côté serveur, clés et cas d'erreur – l'intégration complète en un seul endroit.

Démarrage rapide Configurer un domaine de test

Comment le script et la vérification côté serveur fonctionnent ensemble

Une intégration complète comporte deux moitiés : le script dans le navigateur et une vérification sur votre serveur.

1
Le script se charge
Votre page charge client.js?k=… avec votre clé de site. Le script mesure le comportement dans le formulaire.
2
Le formulaire est envoyé
À l'envoi, le script transmet la mesure et ajoute le champ behavior_nonce à votre formulaire.
3
Votre serveur interroge
Votre serveur envoie behavior_nonce à POST /api/v1/captcha/verify-nonce, avec votre clé dans l'en-tête X-Api-Key.
4
Vous décidez
La réponse contient ok, verdict, confidence et reason_codes. Acceptez l'envoi si ok vaut true, sinon refusez-le.

Sans l'étape 3, l'intégration ne protège qu'à moitié : le script seul n'arrête pas une requête envoyée directement à votre serveur.

Clé de site et clé serveur

Clé de site (publique)

client.js?k=…

Elle figure dans le code source de votre page et est donc visible par tous. Elle lie le script à votre domaine ; les sous-domaines tels que www. ou staging. sont inclus.

Clé serveur (secrète, facultative)

X-Api-Key

Facultatif. Si vous souhaitez que les appels de votre serveur portent une valeur absente du code source de votre page, créez-la dans le tableau de bord, sur la clé, dans l'onglet « Clé serveur ». Elle ne doit se trouver que sur votre serveur, jamais dans le navigateur, et peut être régénérée à tout moment.

La vérification côté serveur fonctionne avec la seule clé de site, vous n'avez donc rien à modifier. Les deux clés sont acceptées. Avec la clé serveur, votre code serveur ne contient aucune valeur que n'importe qui pourrait lire dans le code source de votre page.

Démarrage rapide

Installer et intégrer

Ajouter le script et obtenir un jeton (token)

Vérifier sur le serveur

Valider le jeton sur votre backend

Test rapide avec cURL

Vérifier le nonce via la ligne de commande

# Vérifier le Nonce
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>

Sécurité et confidentialité

Pas de cookies – fonctionnement entièrement sans cookies
Aucun profil, aucun cookie – utilisable conformément au RGPD
Hébergement dans l’EU – vérification et stockage sur nos serveurs en Allemagne
Conforme WCAG – accessible à tous les utilisateurs
Compatible CSP – à utiliser avec une 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 et Bibliothèques

Le paquet s'exécute sur votre serveur (Node.js 18 ou plus). Dans le navigateur, aucun paquet n'est nécessaire : l'extrait client.js du démarrage rapide suffit.

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

Agents d'IA (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

Référence de l'API

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

POST/api/v1/captcha/verify-nonce

Vérifier le Nonce SilentShield

Request Headers:

X-Api-KeyYOUR_API_KEY

Content-Typeapplication/json

Request Body:

noncestringLe Nonce à vérifier

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 vérifié avec succès

400Requête invalide (Nonce manquant ou incorrect)

401Clé API invalide

403Non confirmé comme humain (ok : false) – refusez l’envoi

429Limite de taux dépassée

500Erreur interne du serveur

Délais d'attente, pannes et quota

Définissez un délai d'attente pour la vérification côté serveur. Nos exemples de code utilisent 5 secondes.
Si la vérification ne répond pas à temps, les exemples la traitent comme « non confirmée » et refusent. Si vous préférez accepter dans ce cas, interceptez l'erreur vous-même — la décision vous appartient.
Si le premier hôte ne répond pas pendant que le script charge ses paramètres et ses composants, il bascule sur le second (api.silentshield.io et api-eu.silentshield.io). Les clés à liaison UE stricte restent sur l'hôte UE.
Il n'existe pas d'hôte de secours automatique pour la vérification côté serveur.
Au-delà de votre quota mensuel, l'API continue de vérifier et répond normalement. Un 429 signifie que la limite de requêtes par minute de votre clé a été dépassée.

Tester en local et sur un domaine de test

Votre clé ne fonctionne pas sur localhost : elle est liée à votre domaine, et le script y est refusé.
Testez sur un sous-domaine de votre domaine, par exemple staging.votre-domaine.fr. Il fonctionne avec la clé du domaine principal et n'occupe pas d'emplacement de domaine supplémentaire.
Si vous souhaitez évaluer séparément le test et la production, créez une deuxième clé pour le même domaine. Elle n'occupe pas non plus d'emplacement de domaine supplémentaire.
Envoyez un formulaire à titre de test et vérifiez la réponse de verify-nonce sur votre serveur : une saisie manuelle devrait renvoyer ok: true ; sinon, les reason_codes indiquent pourquoi.

Configurer un domaine de test

Versions et modifications

L'API porte sa version dans le chemin : /api/v1. Les mêmes routes sont disponibles sous /api.
Le script n'a pas de numéro de version : client.js fournit toujours la version actuelle, vous n'avez donc rien à mettre à jour.
Les SDK pour PHP, Node, Go et Edge ont des numéros de version ; les modifications figurent dans le changelog de chaque paquet.
Nous publions les modifications de l'API et du script dans le changelog.

Ressources

Centre d'aide

Documentation complète avec guides de démarrage, tutoriels d'intégration, références de configuration et dépannage.

Ouvrir le centre d'aide

Journal des modifications

Restez informé des dernières fonctionnalités, améliorations et corrections.

Voir le journal des modifications

Prêt à commencer ?

Créez un compte gratuit et obtenez votre clé.

Commencer