# 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é
```
ifp_live_9f2c4a7b1e8d3406af5b2c9d1e0f7a83
└┬─┘ └┬─┘ └──────────────┬──────────────┘
│ │ └─ secret aléatoire, jamais réaffiché
│ └─ environnement : live ou test
└─ produit : API partenaire Instafuel
```
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.
1. **Demandez l'ouverture du compte** auprès de votre interlocuteur Instafuel.
2. **Recevez votre clé de test** (`ifp_test_*`). Elle est immédiate et sans engagement : construisez et validez toute votre intégration avec.
3. **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`.
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 :
1. **Demandez une nouvelle clé.** L'ancienne reste active.
2. **Déployez la nouvelle** dans votre configuration. Vérifiez avec `GET /v1/papi/me` qu'elle répond `200` depuis vos serveurs de production.
3. **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.
4. **Révoquez l'ancienne** et vérifiez qu'aucun `401 PAPI_KEY_INVALID` n'apparaît dans vos journaux.
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.