Authentification
EFact utilise des clés API secrètes pour authentifier les requêtes. La clé identifie et authentifie votre organisation : vous ne passez jamais d'identifiant d'organisation dans vos appels.
En bref
L'API EFact s'authentifie avec des clés secrètes préfixées efact_sk_, transmises dans l'en-tête Authorization: Bearer. Chaque clé est rattachée à une seule organisation (isolation multi-tenant). Les SDK lisent la clé depuis la variable d'environnement EFACT_SECRET_KEYet l'ajoutent automatiquement à chaque requête.
La clé secrète
| Type | Préfixe | Utilisée par | Accès |
|---|---|---|---|
| Clé secrète | efact_sk_... | Backend uniquement (serveur à serveur) | Toutes les opérations factures de votre organisation (/v1/invoices) |
Règle absolue : ne jamais exposer la clé secrète côté frontend ou dans un dépôt Git. Pour afficher un statut de facture dans un navigateur, faites transiter la requête par votre backend.
Utiliser la clé secrète
Via le header HTTP
POST /v1/invoices
Authorization: Bearer efact_sk_abc123...
Content-Type: application/jsonVia le SDK Node
const efact = new EFact(process.env.EFACT_SECRET_KEY!)La clé secrète est passée à l'initialisation du client - elle est incluse dans chaque requête automatiquement, exclusivement dans le header Authorization(jamais dans l'URL).
Environnements
Le SDK pointe par défaut sur la production (https://api.efact.ma). Pour le développement local ou un environnement de test, surchargez l'URL de base :
const efact = new EFact(process.env.EFACT_SECRET_KEY!, {
baseUrl: 'http://localhost:8080',
})Variables d'environnement recommandées
# .env (ne jamais committer ce fichier)
EFACT_SECRET_KEY=efact_sk_...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.
Seule l'empreinte de la clé (hachage unidirectionnel SHA-256d'une clé à 256 bits d'entropie) est conservée en base de données. 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 | Code erreur | Cause | Solution |
|---|---|---|---|
401 Unauthorized | API_KEY_MISSING | Clé manquante ou header mal formaté | Vérifier Authorization: Bearer efact_sk_... |
401 Unauthorized | API_KEY_INVALID | Clé invalide ou révoquée | Regénérer la clé dans le dashboard |
429 Too Many Requests | API_KEY_RATE_LIMITED | Plus de 300 requêtes/minute avec la même clé | Respecter le header Retry-After (le SDK le fait automatiquement) |
Questions fréquentes
Comment s'authentifier auprès de l'API EFact ?
L'API EFact utilise des clés secrètes préfixées efact_sk_, transmises dans l'en-tête HTTP Authorization: Bearer. Chaque requête est ainsi rattachée à votre organisation. Le SDK Node.js lit la clé depuis une variable d'environnement (EFACT_SECRET_KEY) et l'ajoute automatiquement à chaque appel.
Comment protéger sa clé API EFact ?
Une clé secrète efact_sk_ ne doit jamais être exposée côté client ni committée dans le code. Stockez-la dans une variable d'environnement ou un gestionnaire de secrets, utilisez des clés distinctes par environnement, et faites-la tourner en cas de compromission. Toute clé exposée doit être révoquée immédiatement.
Une clé API donne-t-elle accès aux données d'autres organisations ?
Non. Chaque clé est rattachée à une seule organisation et l'API est strictement cloisonnée par organisation (isolation multi-tenant). Une clé ne peut lire ni modifier que les factures et paramètres de son organisation, ce qui empêche tout accès croisé entre clients.