Clés d'API
Une clé d'API partenaire identifie votre compte apporteur, porte ses droits et détermine son périmètre. Cette page couvre son cycle de vie complet.
Anatomie d'une clé
Code
Le préfixe est lisible et stable. Le secret ne l'est pas : il n'est affiché qu'une seule fois, à la création. Instafuel n'en conserve qu'une empreinte et ne peut pas vous le redonner. Perdu, il faut faire tourner la clé.
Obtenir une clé
Les clés ne s'auto-provisionnent pas : elles sont émises par Instafuel à l'ouverture de votre compte apporteur, après signature du contrat de partenariat.
-
Demandez l'ouverture du compte auprès de votre interlocuteur Instafuel.
-
Recevez votre clé de test (
ifp_test_*). Elle est immédiate et sans engagement : construisez et validez toute votre intégration avec. -
Demandez la clé de production (
ifp_live_*) quand votre intégration est prête. Instafuel vous demandera les adresses IP sortantes de vos serveurs et les droits nécessaires.
Droits
Une clé ne porte que les droits qu'on lui a donnés. Demandez le minimum dont vous avez besoin — c'est ce qui limite les dégâts si elle fuite.
| Droit | Permet |
|---|---|
COMPANIES_READ | lire les entreprises de votre portefeuille |
COMPANIES_WRITE | demander l'enrôlement d'une entreprise, modifier une fiche |
USERS_READ | lire les comptes web de vos clients |
USERS_WRITE | créer et modifier des comptes web chez vos clients |
WALLET_READ | lire les soldes Fuelz et suivre vos déclarations de versement |
LEDGER_READ | lire les écritures d'un wallet |
TRANSACTIONS_READ | lire les pleins |
DRIVERS_READ | lire les portefeuilles chauffeurs — contient des données personnelles |
ALERTS_READ | lire les alertes des entreprises du portefeuille |
REPORTS_READ | lire la synthèse du portefeuille |
CREDIT_REQUEST_WRITE | déposer une preuve et déclarer un versement (jamais créditer directement) |
Un appel hors des droits de la clé renvoie 403 PAPI_SCOPE_MISSING, sans aucun effet. Le message nomme le droit manquant : vous savez immédiatement quoi demander.
GET /v1/papi/me renvoie à tout moment les droits que porte la clé utilisée, et ceux qu'Instafuel a autorisés sur votre compte. Vous ne pouvez pas vous attribuer un droit hors de ce plafond — la création de clé le refuse en 422 PAPI_SCOPE_ABOVE_CEILING.
Une clé par usage
Séparez ce qui n'a pas la même surface de risque : une clé en lecture seule pour votre tableau de bord interne, une clé en écriture pour votre back-office d'onboarding. Le jour où l'une fuite, vous révoquez sans arrêter le reste.
Restriction par adresse IP
Une clé de production peut être limitée à une liste d'adresses IP sortantes. Un appel depuis une autre adresse est refusé en 403 PAPI_IP_FORBIDDEN, même si la clé est valide.
C'est la protection la plus efficace contre une clé exfiltrée : le secret ne suffit plus, il faut aussi appeler depuis votre infrastructure.
Prévenez Instafuel avant de changer d'hébergeur ou d'ajouter une passerelle sortante — sinon la coupure est immédiate et totale.
Rotation
Faites tourner vos clés de production au moins une fois par an, et immédiatement si l'une d'elles a pu être exposée : commit accidentel, ordinateur perdu, départ d'un prestataire.
La rotation se fait sans interruption de service, à condition de respecter l'ordre :
-
Demandez une nouvelle clé. L'ancienne reste active.
-
Déployez la nouvelle dans votre configuration. Vérifiez avec
GET /v1/papi/mequ'elle répond200depuis vos serveurs de production. -
Laissez tourner les deux le temps que tous vos processus aient rechargé leur configuration — tâches planifiées et files d'attente comprises, elles sont souvent les dernières.
-
Révoquez l'ancienne et vérifiez qu'aucun
401 PAPI_KEY_INVALIDn'apparaît dans vos journaux.
L'ordre compte
Révoquer avant d'avoir déployé coupe votre intégration jusqu'au prochain déploiement. Une clé révoquée ne se réactive pas.
Révocation
Demandez la révocation à votre interlocuteur Instafuel, avec le préfixe de la clé concernée — jamais la clé entière dans un email.
La révocation est immédiate et définitive. Tout appel présentant la clé renvoie ensuite 401 PAPI_KEY_INVALID.
En cas de fuite avérée, révoquez d'abord et enquêtez ensuite : une clé compromise donne une vue complète sur votre portefeuille et permet d'onboarder des entreprises en votre nom.
Hygiène
- Stockez la clé dans un gestionnaire de secrets, ou à défaut dans une variable d'environnement. Jamais dans le dépôt.
- Ajoutez un filtre à vos journaux : une clé recopiée dans une trace d'erreur est une clé publiée.
- Ne transmettez jamais une clé par email ou messagerie. Utilisez un canal chiffré à usage unique.
- Journalisez le préfixe utilisé par vos appels sortants (
ifp_live_9f2c…). En cas d'incident, vous saurez laquelle révoquer. - Sur staging, considérez que la clé de test est jetable : la fuite y coûte peu, ce qui n'est pas une raison pour l'exposer.