Authentification
EFact utilise des clés API pour authentifier les requêtes. Deux types de clés existent, chacun avec un périmètre d'usage distinct.
Types de clés
| Type | Préfixe | Utilisée par | Accès |
|---|---|---|---|
| Clé secrète | sk_live_xxx / sk_test_xxx | Backend uniquement | Écriture + lecture (tous endpoints) |
| Clé publiable | pk_live_xxx / pk_test_xxx | Frontend (navigateur) | Lecture seule via client_secret |
Règle absolue : ne jamais exposer la clé secrète côté frontend ou dans un dépôt Git.
Utiliser la clé secrète
Via le header HTTP
POST /v1/invoices
Authorization: Bearer sk_live_abc123...
Content-Type: application/jsonVia le SDK Node
const itz = new Itzenata(process.env.ITZENATA_SECRET_KEY)Via le SDK Java
Itzenata itz = new Itzenata(System.getenv("ITZENATA_SECRET_KEY"));La clé secrète est passée à l'initialisation du client - elle est incluse dans chaque requête automatiquement.
Utiliser la clé publiable
La clé publiable est destinée à être embarquée dans le code frontend. Elle ne permet pas de créer des ressources - elle donne uniquement accès au statut d'une facture via son client_secret.
<ItzenataProvider publishableKey="pk_live_xyz789">
<InvoiceStatus clientSecret={clientSecret} />
</ItzenataProvider>Le client_secretest un token unique par facture, généré côté backend et transmis au frontend. Il ne donne accès qu'à cette unique facture.
Environnements
| Environnement | Préfixe des clés | Comportement DGI |
|---|---|---|
| Test | sk_test_ / pk_test_ | Transmission mockée (aucun appel DGI réel) |
| Live | sk_live_ / pk_live_ | Transmission réelle vers la DGI |
Utiliser systématiquement les clés test en développement et préproduction.
Variables d'environnement recommandées
# .env (ne jamais committer ce fichier)
ITZENATA_SECRET_KEY=sk_test_...
ITZENATA_PUBLISHABLE_KEY=pk_test_...
ITZENATA_WEBHOOK_SECRET=whsec_...Important : ne jamais committer ce fichier dans votre dépôt Git.
Gestion des clés dans le dashboard
- 1Créer une clé : Dashboard > API Keys > Nouvelle clé
- 2Voir le préfixe : la clé complète n'est affichée qu'à la création - copier immédiatement
- 3Révoquer une clé : Dashboard > API Keys > Révoquer - effet immédiat, toutes les requêtes en cours avec cette clé sont rejetées
- 4Rotation : créer la nouvelle clé, déployer avec la nouvelle valeur, puis révoquer l'ancienne
Sécurité et stockage de vos clés
Pour garantir une sécurité maximale de vos données fiscales, EFact ne stocke jamais vos clés secrètes en clair.
Elles sont protégées en base de données par un algorithme de hachage unidirectionnel fort (bcrypt), conformément aux standards de sécurité de l'industrie. Ainsi, même en cas d'audit ou d'accès interne, personne ne peut lire votre clé. Si vous suspectez une fuite de votre côté, la révocation depuis votre Dashboard la neutralise instantanément.
Erreurs d'authentification courantes
| Code HTTP | Cause | Solution |
|---|---|---|
401 Unauthorized | Clé manquante ou header mal formaté | Vérifier Authorization: Bearer sk_... |
401 Unauthorized | Clé invalide ou révoquée | Regénérer la clé dans le dashboard |
403 Forbidden | Clé publiable utilisée sur un endpoint d'écriture | Utiliser la clé secrète côté backend |
403 Forbidden | client_secret ne correspond pas au tenant | Vérifier que le client_secret vient bien du même tenant |