Pourquoi configurer une whitelist de domaines pour votre clé API GreenCalc

Une clé API qui fuite sur un dépôt public peut être exploitée en quelques heures. La whitelist de domaines (allowed_domains) bloque toute requête depuis un domaine non listé, même si la clé est techniquement valide. Voici comment activer cette protection en 2 minutes et pourquoi c’est la défense la plus efficace contre les fuites accidentelles.

Publié le 25 avril 2026 · 8 minutes de lecture · Par GreenCalc — AZMORIS Group

1. Le scénario réel d’une clé qui fuite

Un développeur travaille sur l’intégration GreenCalc d’un site artisan RGE. Il copie sa clé API gc_live_xxxxx dans un fichier .env. Quelques jours plus tard, par réflexe ou mégarde, il commit et push ce fichier sur GitHub.

Le repo est public. Des bots scannent en permanence les nouveaux commits à la recherche de chaînes ressemblant à des clés API (regex sur les préfixes connus comme gc_, sk_, AKIA, etc.). En moins de 4 heures, la clé est récupérée par un acteur malveillant.

L’attaquant lance un script qui consomme 1 000 simulations en 10 minutes. Le compte du développeur atteint 80% de son quota mensuel dès le lendemain matin (alerte email automatique GreenCalc). Sans intervention, la clé aurait épuisé le quota mensuel complet en moins de 24h.

2. Les protections déjà en place chez GreenCalc

Avant même de configurer une whitelist, GreenCalc applique plusieurs filets de sécurité automatiques :

• Rate limiting Nginx : 2 requêtes par seconde par IP, burst de 10. Une attaque massive est ralentie dès la 11ème requête.
• Quota mensuel hard-block : au-delà de 110% du quota, la clé renvoie 429 Too Many Requests jusqu’au 1er du mois suivant.
• Alerte email WARN_80 : à 80% du quota mensuel, le propriétaire de la clé reçoit un email. Permet de détecter une utilisation anormale en quelques heures plutôt qu’en quelques jours.
• Watermark sandbox : les clés gc_sandbox_ renvoient des données fictives marquées [SANDBOX]. Inutilisables en production.
• Hash SHA-256 en BDD : la clé n’est jamais stockée en clair côté serveur.

Ces protections sont robustes, mais réactives : elles agissent une fois l’abus en cours. La whitelist, elle, est préventive.

3. La whitelist : la couche ultime

Le principe est simple : chaque clé API peut être associée à une liste de domaines autorisés. Toute requête dont l’Origin ou le Referer n’apparaît pas dans la liste est rejetée en HTTP 403, même si la clé est correcte.

Sans configuration explicite, le mode est permissif par défaut (la clé fonctionne depuis n’importe où). Aucun client GreenCalc existant n’est cassé par l’activation de cette feature : seul ceux qui ont configuré une whitelist sont contrôlés.

4. Trois cas d’usage concrets

Cas 1 — Artisan RGE avec un site vitrine

Vous intégrez le widget GreenCalc sur votre site monsite-rge.fr. Whitelist recommandée :

monsite-rge.fr
*.monsite-rge.fr

Cela couvre monsite-rge.fr, www.monsite-rge.fr, et tout sous-domaine que vous pourriez ajouter (blog.monsite-rge.fr, devis.monsite-rge.fr).

Cas 2 — Mandataire CEE avec plusieurs sites partenaires

Vous gérez les sites de 5 partenaires sous différents domaines. Whitelist :

cabinet-energie.fr
*.cabinet-energie.fr
artisan-renov-paris.com
*.artisan-renov-paris.com
... (jusqu'a 50 entrees max)

Cas 3 — Néobanque avec un CDN devant son app

Votre app principale est sur app.neobanque.fr mais utilise un CDN qui présente l’Origin différemment :

app.neobanque.fr
api.neobanque.fr
*.cdn.neobanque.fr

Vérifiez via l’outil « Tester un Origin » dans la modal du dashboard que tous vos URLs réels passent. La preview est instantanée.

5. Configurer en 2 minutes

1. Connectez-vous : https://greencalc.io/dashboard
2. Section « Mes clés API »
3. Cliquez sur le badge « Aucune restriction » (jaune) à côté de votre clé
4. Listez vos domaines (1 par ligne, 50 max)
5. Utilisez l’outil « Tester un Origin » pour vérifier que vos URLs réels passent
6. Cliquez « Enregistrer »

La protection est immédiate. Le badge passe au vert « X domaines ».

6. Bonnes pratiques

• Wildcards plutôt qu’exhaustif : *.monsite.fr couvre tous sous-domaines actuels et futurs. Plus simple à maintenir qu’une liste de 10 sous-domaines explicites.
• Inclure les environnements de staging : si votre staging tourne sur staging.monsite.fr, l’ajouter explicitement évite des surprises lors des tests.
• Tester avant d’enregistrer : la modal inclut un « Origin tester » qui valide instantanément côté client sans toucher à la prod.
• Documenter dans votre runbook : noté quels domaines sont autorisés sur quelle clé. Lors d’un changement de domaine (acquisition, refonte), pensez à mettre à jour.
• Combiner avec rotation de clé : générer une nouvelle clé tous les 6 mois, même sans incident. La whitelist limite l’impact d’une fuite ; la rotation l’efface complètement.

7. Ce que la whitelist ne fait PAS

Pour rester transparent :

• Ne protège pas contre une attaque depuis votre propre serveur compromis. Si l’attaquant a accès à votre infra, il peut faire des requêtes avec un Origin valide.
• Ne remplace pas la rotation de clé. Un attaquant qui obtient accès temporaire à un de vos serveurs peut quand même consommer votre quota tant que la clé reste active.
• N’agit que sur les requêtes navigateur (qui envoient Origin automatiquement). Une requête server-to-server doit explicitement inclure le header. Les bots récents savent forger un Origin, mais c’est rare.

La whitelist est une couche de plus dans une stratégie de défense en profondeur, pas une silver bullet.

8. Questions fréquentes