Sécurité

Protégez vos clés, vos webhooks et l’argent de vos clients.

Votre clé d’API peut déplacer de l’argent. Traitez-la comme un mot de passe bancaire, et considérez chaque webhook comme suspect tant que sa signature n’est pas vérifiée.

Gardez les clés sur votre serveur#

• Appelez l’API uniquement depuis votre serveur. Jamais depuis une page web, une extension de navigateur ou une application mobile : n’importe qui peut lire une clé livrée sur un appareil. Votre application parle à votre serveur, votre serveur parle à Monerail.
• Chargez la clé depuis une variable d’environnement ou un coffre de secrets. Ne la versionnez jamais, ne la collez jamais dans un ticket ou une messagerie.
• Utilisez des clés de test (mr_test_) partout sauf en production. Dans vos tests, vérifiez "livemode": false sur ce que vous recevez.
• Nommez chaque clé d’après l’endroit où elle sert (2 à 60 caractères), pour savoir laquelle révoquer.

Donnez à chaque clé le plus petit rôle#

Une clé agit avec le rôle du membre qui l’a créée (tableau). Créez les clés de production depuis un compte membre dédié, avec le seul rôle dont l’intégration a besoin :

Renouvelez et révoquez#

• Pour renouveler une clé : créez la nouvelle, déployez-la, vérifiez que le trafic l’utilise, puis révoquez l’ancienne. Vous pouvez avoir 20 clés actives : les deux peuvent coexister un moment.
• Une clé révoquée cesse aussitôt de fonctionner.
• Quand un membre quitte l’entreprise, toutes les clés qu’il a créées cessent de fonctionner (401 api_key_owner_removed). Préparez leur remplacement avant de retirer quelqu’un.
• Renouvelez les clés quand une personne qui y avait accès quitte votre équipe, et immédiatement si une clé a pu fuiter.

Vérifiez chaque webhook#

• Vérifiez la signature de chaque événement avec le secret du point de terminaison, sur le corps brut, avec une comparaison en temps constant, et refusez les horodatages de plus de 5 minutes.
• Utilisez une adresse HTTPS avec un nom de domaine. Monerail refuse les adresses IP et les adresses avec utilisateur:mot_de_passe@, et n’envoie jamais vers une adresse privée, de bouclage, lien-local ou réservée.
• Le secret ne s’affiche qu’une fois. Pour le renouveler, créez un second point de terminaison avec la même adresse, acceptez les deux secrets un moment, puis supprimez l’ancien. Dédoublonnez les événements par id : pendant cette période, chaque événement arrive deux fois.

Ne payez jamais deux fois#

Envoyez une Idempotency-Key sur chaque POST qui déplace de l’argent (encaissements, paiements, reversements, émission et recharge de cartes), et reprenez la même clé quand vous réessayez. Traitez 202 comme « en route » : ne recréez jamais l’opération, attendez le webhook.

Transport et journaux#

• L’API ne fonctionne qu’en HTTPS et envoie Strict-Transport-Security. Laissez la vérification des certificats active dans votre client HTTP.
• Journalisez le Request-Id de chaque appel. Ne journalisez jamais l’en-tête Authorization, les secrets de webhook ni les pièces d’identité.
• Les messages d’erreur s’adressent aux développeurs et ne contiennent jamais de détail interne ou de partenaire. Affichez vos propres messages à vos clients.

Ce que fait Monerail#

• Ne garde qu’une empreinte de chaque clé d’API ; la clé complète ne s’affiche qu’une fois.
• Exige la double authentification pour créer des clés d’API.
• Vérifie le rôle de la clé avant d’agir, et avant d’enregistrer la moindre pièce d’identité.
• Signe chaque webhook en HMAC-SHA256 avec un horodatage, et bloque les envois vers les adresses privées.
• Limite le débit des requêtes par clé et par entreprise (Limites de débit).
• Ne renvoie jamais le numéro complet ni le CVC d’une carte par l’API. Un membre Propriétaire ou Finance peut les afficher 60 secondes dans le tableau de bord.
• Vérifie les identités par entreprise : une personne vérifiée par une autre entreprise est vérifiée à nouveau pour la vôtre.
• Ne laisse qu’un Propriétaire modifier les comptes de reversement, dans le tableau de bord ; l’API ne le peut pas.

Pour signaler un problème de sécurité, écrivez à support@monerail.com.