Authentification
Clés d’API, mode test et production, et rôles qui décident de ce qu’une clé peut faire.
Chaque requête porte une clé d’API secrète dans l’en-tête Authorization :
curl https://api.monerail.com/v1/balance \
-H "Authorization: Bearer mr_live_3f9c…"Une requête sans clé valide échoue avec 401 authentication_error.
Les clés
| Préfixe | Mode | Agit sur |
|---|---|---|
mr_test_ |
Test | Les objets de test seulement. Aucun argent réel. |
mr_live_ |
Production | L’argent réel. Disponible une fois votre dossier d’entreprise validé. |
Créez les clés dans le tableau de bord, sous Développeurs › Clés d’API. Seul un Propriétaire ou un Développeur peut en créer, et la double authentification doit être activée sur son compte. Une clé porte un nom de 2 à 60 caractères. La clé complète ne s’affiche qu’une fois : Monerail n’en garde qu’une empreinte. Vous pouvez avoir 20 clés actives, et révoquer n’importe laquelle à tout moment ; une clé révoquée cesse aussitôt de fonctionner.
Le tableau de bord passe d’un mode à l’autre avec le sélecteur Test | Production de l’en-tête. La production reste verrouillée jusqu’à la validation de votre dossier d’entreprise ; les clés et les points de terminaison de production en dépendent aussi.
Gardez les clés sur votre serveur. Ne mettez jamais une clé dans un site, une application mobile ou un dépôt public. Chargez-la depuis une variable d’environnement ou un coffre de secrets, et révoquez-la immédiatement en cas de fuite. Voir Sécurité.
Ce qu’une clé peut faire
Une clé agit au nom du membre de l’équipe qui l’a créée, avec le rôle de ce membre. Si son rôle change, la clé suit. S’il quitte l’entreprise, la clé cesse de fonctionner (401 api_key_owner_removed) : créez-en une nouvelle.
| Opération | Rôles autorisés |
|---|---|
| Lire le solde, les encaissements, paiements, reversements, transactions, titulaires, cartes, opérateurs et banques | Tous les rôles |
| Lire les événements | Propriétaire, Finance, Développeur |
| Lire les points de terminaison | Propriétaire, Développeur |
| Créer des encaissements, transmettre des codes | Propriétaire, Finance, Développeur |
| Créer des paiements | Propriétaire, Finance, Valideur |
| Créer des reversements | Propriétaire, Finance |
| Créer et vérifier des titulaires, émettre des cartes | Propriétaire, Finance |
| Recharger, vider, résilier des cartes | Propriétaire, Finance |
| Bloquer, débloquer des cartes | Propriétaire, Finance, Valideur |
| Créer des points de terminaison | Propriétaire, Développeur |
| Supprimer des points de terminaison, renvoyer des événements | Propriétaire, Développeur |
| Outils de test des cartes | Propriétaire, Finance |
Les rôles sont Propriétaire, Finance, Valideur, Développeur et Lecture seule. Le rôle Lecture seule ne fait que lire, et ni un Valideur ni un membre en Lecture seule ne peut lire les événements. Une opération hors du rôle échoue avec 403 permission_denied. Bonne pratique : créez la clé de production depuis un compte membre dédié, avec le seul rôle dont votre intégration a besoin.
En-têtes de réponse
| En-tête | Sens |
|---|---|
Request-Id |
Identifiant unique de la requête (req_…). Donnez-le au support. |
Monerail-Version |
Version de l’API qui a produit la réponse. |
Idempotent-Replayed |
true quand la réponse rejoue une requête antérieure de même Idempotency-Key. |
Retry-After |
Sur un 429, secondes à attendre avant de réessayer. |
Strict-Transport-Security |
Impose HTTPS : l’API ne répond jamais en HTTP simple. |
X-Content-Type-Options |
nosniff. |
Langue
Les messages d’erreur sont en anglais. Envoyez Accept-Language: fr pour les recevoir en français. Les codes ne changent jamais avec la langue.