Clés serveur
Envoyez un formulaire à partir de votre propre serveur avec plus de marge, et comptez chaque visiteur séparément. Une clé serveur est facultative : tous les formulaires continuent de fonctionner sans elle.
Sans clé, Formerie voit l’adresse de votre serveur, alors tous vos visiteurs partagent une même limite. Avec une clé :
- Votre serveur peut nommer le visiteur, alors la limite par visiteur compte chaque personne.
- Votre serveur a des limites plus élevées. Voir Ce qui change.
- Tout le reste demeure actif. La validation, les vérifications antipourriel, la vérification humaine, les horaires, les quotas et vos propres limites s’appliquent toujours.
Une clé peut seulement faire ce qu’un visiteur peut faire : lire le schéma d’un formulaire, vérifier des réponses et soumettre. Elle ne peut ni lire les soumissions ni modifier un formulaire.
Créer une clé
Dans l’application, ouvrez votre espace de travail, puis Clés serveur. Les propriétaires et les administrateurs de l’espace peuvent le faire.
- Choisissez Nouvelle clé et donnez-lui un nom, comme celui du site qui va l’utiliser.
- Choisissez si elle fonctionne sur tous les formulaires de l’espace ou sur un seul. Un seul formulaire, c’est plus sûr.
- Choisissez sa durée : 90 jours, 1 an ou 2 ans.
- Copiez la clé et placez-la dans les secrets de votre serveur. Elle n’est affichée qu’une seule fois. Formerie n’en garde qu’une empreinte, alors personne ne peut vous la réafficher.
Une clé commence par fmc_. Gardez-la hors de votre code et de votre dépôt, et lisez-la à partir d’une variable d’environnement.
Utiliser une clé
Envoyez la clé dans l’en-tête Authorization, et l’adresse du visiteur dans X-Formerie-Visitor-Ip :
curl https://forms.formerie.com/fm_t77txbvg43nmar/submit \
-H "Authorization: Bearer $FORMERIE_SERVER_KEY" \
-H "X-Formerie-Visitor-Ip: 203.0.113.42" \
-H "Content-Type: application/json" \
-d '{"fields":{"email":"visitor@example.com","message":"Hello"}}'Ça fonctionne de la même façon sur les trois routes de la référence de l’API.
La garder sur votre serveur
Un navigateur ne peut pas utiliser une clé. Formerie refuse toute requête qui contient une clé et un en-tête Origin ou Sec-Fetch-Site, avec API_KEY_FROM_BROWSER, même à partir d’un site de votre liste autorisée. N’envoyez pas Origin à partir de votre serveur avec une clé.
Si une vraie clé arrive de cette façon, l’onglet Clés serveur affiche un avertissement. Une clé qui s’est retrouvée dans une page Web doit être considérée comme publique, alors faites-en la rotation.
L’adresse du visiteur
Envoyez une seule adresse IPv4 ou IPv6, celle de la personne qui utilise votre site. Votre serveur doit la prendre d’une source fiable, habituellement l’adresse que lui donne votre répartiteur de charge ou votre hébergeur.
| Vous envoyez | Ce qui se passe |
|---|---|
| Une adresse publique, avec une clé | Elle sert à la limite par visiteur et elle est transmise au fournisseur de vérification humaine. Une soumission garde seulement un hachage de l’adresse. Les journaux de requêtes, conservés jusqu’à 7 jours, peuvent contenir l’adresse, comme pour toute personne qui arrive directement à un formulaire |
| Rien, avec une clé | Les limites par adresse ne s’appliquent pas, puisque Formerie ne compte pas votre serveur comme un visiteur. Aucune adresse n’est conservée |
Une adresse privée, comme 10.0.0.8 ou 127.0.0.1, avec une clé | Elle est ignorée comme si vous n’aviez rien envoyé, et la réponse contient l’avis VISITOR_IP_NOT_PUBLIC. Les essais à partir de votre ordinateur fonctionnent ainsi |
Autre chose, comme une liste X-Forwarded-For complète, avec une clé | Refusé avec INVALID_VISITOR_IP, alors vous le voyez dès votre premier essai |
| N’importe quelle adresse, sans clé | Elle est ignorée, et la réponse contient l’avis VISITOR_IP_IGNORED. Seule une clé amène Formerie à s’y fier |
Vous transmettez les adresses de vos visiteurs, alors assurez-vous que votre propre avis de confidentialité en parle.
Ce qui change
| Limite | Sans clé | Avec une clé |
|---|---|---|
| Limite à court terme sur les routes publiques | 120 requêtes par minute, par formulaire et par adresse | 120 par minute par visiteur, jusqu’à environ 1 200 par minute par formulaire pour la clé |
| Limite par visiteur par défaut | 30 par tranche de 10 minutes, partagées par tous sur votre serveur | 30 par tranche de 10 minutes pour chaque visiteur |
| Limite par formulaire par défaut | 1 000 par heure | 10 000 par heure par clé |
Les limites que vous avez fixées vous-même sur un formulaire s’appliquent telles quelles, et une limite par adresse a besoin de l’adresse du visiteur pour compter quoi que ce soit. Avec le forfait gratuit, un formulaire accepte au plus 1 000 soumissions par heure, avec ou sans clé. Voir Forfaits et limites.
La vérification humaine
Avec une clé, vous n’avez pas à transmettre Origin. Envoyez le jeton dans verificationToken, et Formerie accepte un jeton obtenu sur n’importe quel site des origines autorisées du formulaire. Il vous faut quand même vos propres clés du fournisseur, comme l’explique La vérification avec un serveur.
Faire la rotation d’une clé
Choisissez Rotation sur la clé. Vous obtenez une nouvelle clé, affichée une seule fois, avec le même nom et le même formulaire. Les deux clés fonctionnent pendant les 24 prochaines heures, ce qui vous laisse le temps d’installer la nouvelle sur votre serveur sans aucun refus. Ensuite, l’ancienne cesse de fonctionner.
Un mois avant l’expiration d’une clé, le propriétaire de l’espace reçoit un courriel, ce qui laisse le temps d’en faire la rotation.
Révoquer une clé
Choisissez Révoquer sur la clé. Elle cesse de fonctionner aussitôt. Si une clé a fuité, révoquez-la au lieu d’en faire la rotation, puis créez-en une nouvelle.
Une clé qui échoue est toujours refusée. La requête de votre serveur ne passe jamais sans elle, alors une erreur se voit au lieu de faire partager en silence une même limite. Quand ça arrive, gardez ce que votre visiteur a écrit et affichez un message calme, et basez-vous sur ces codes :
| Code | État | Signification |
|---|---|---|
API_KEY_INVALID | 401 | La clé est erronée ou l’en-tête est mal formé |
API_KEY_EXPIRED | 401 | La date de la clé est passée, ou les 24 heures après une rotation sont écoulées |
API_KEY_REVOKED | 401 | Quelqu’un a révoqué la clé |
API_KEY_WRONG_FORM | 403 | La clé appartient à un autre formulaire ou à un autre espace |
API_KEY_FROM_BROWSER | 403 | La requête est arrivée avec les en-têtes d’un navigateur |
INVALID_VISITOR_IP | 400 | L’adresse du visiteur n’est pas une seule adresse |
Suivre vos clés
L’onglet Clés serveur affiche le nom de chaque clé, son début, son formulaire, qui l’a créée, sa dernière utilisation et sa date d’expiration. La création, la rotation et la révocation d’une clé paraissent dans l’activité de l’espace, et chaque soumission indique la clé qui l’a envoyée.
Une clé appartient à l’espace, alors elle continue de fonctionner quand la personne qui l’a créée s’en va. Les outils d’IA connectés par MCP ne peuvent ni voir ni créer de clés.
Les paquets officiels n’ont pas encore d’option pour une clé. D’ici là, envoyez les deux en-têtes vous-même.