Clé secrète Supabase (service_role) : le passe-partout de ta base

Supabase fournit deux familles de clés. La première, publique, peut circuler dans le navigateur parce que les règles Row Level Security la filtrent. La seconde, secrète, passe outre toutes ces règles. C'est un outil d'administration, très utile côté serveur, et c'est la clé qui ne doit jamais quitter le serveur.

Deux générations de clés

Supabase a introduit un nouveau système de clés, qui remplace progressivement l'ancien :

La documentation Supabase précise que la clé secrète passe par le rôle Postgres service_role, qui possède l'attribut bypassrls. Supabase annonce la dépréciation des anciennes clés anon et service_role d'ici fin 2026. Créer les nouvelles clés ne révoque pas les anciennes : elles restent actives tant que tu ne les désactives pas dans Settings, puis API Keys.

Supabase ajoute une protection utile : une clé secrète utilisée depuis un navigateur est refusée avec une erreur 401, détectée grâce à l'en-tête User-Agent. C'est un bon garde-fou pour les nouvelles clés, qui ne couvre pas une ancienne clé service_role ni une clé copiée dans un script ou une app mobile.

À quoi sert la clé secrète

Elle est faite pour les traitements que personne ne déclenche directement depuis l'écran, ou qui doivent agir au-delà des droits d'un utilisateur :

• Un webhook de paiement qui met à jour l'abonnement d'un client après un paiement Stripe
• Une tâche planifiée qui archive les anciennes données ou envoie un rapport
• Une fonction d'administration qui crée un compte, réinitialise un accès ou fusionne des doublons
• Une migration ou un import de données en masse

Dans une app Supabase, ces traitements vivent dans des Edge Functions. Supabase met à leur disposition les clés du projet sous forme de variables d'environnement (SUPABASE_SECRET_KEYS, ou l'ancienne SUPABASE_SERVICE_ROLE_KEY), lues avec Deno.env.get. La clé reste sur le serveur et n'apparaît jamais dans les fichiers envoyés au navigateur.

Comment elle se retrouve au mauvais endroit

Le scénario le plus courant dans une app construite avec l'IA est très simple. Une fonctionnalité bute sur une règle RLS : la liste reste vide, l'enregistrement échoue. L'outil cherche à faire passer la fonctionnalité et trouve une solution qui marche immédiatement, en utilisant la clé qui ne connaît aucune règle. L'écran fonctionne, le problème semble résolu, et la clé administrateur se retrouve dans le code livré à chaque visiteur.

Deux autres chemins existent : une clé collée dans un fichier .env envoyé sur GitHub, et une clé écrite en dur dans un script de test resté dans le dépôt. Dans les trois cas, la clé devient un secret exposé.

Comment vérifier ton app

1. Cherche les noms dans le code exporté : service_role, sb_secret_, SERVICE_ROLE. Notre guide sur l'export du code explique comment récupérer le dépôt si ce n'est pas déjà fait
2. Regarde le code servi dans le navigateur : outils de développement, onglet Sources ou Réseau. Une clé administrateur ne doit apparaître dans aucun fichier JavaScript ni dans aucune requête
3. Inspecte l'historique Git, pas seulement la version actuelle. Une clé supprimée du code reste lisible dans les anciens commits
4. Liste les fonctions serveur qui utilisent la clé secrète et vérifie que chacune contrôle elle-même qui l'appelle. Une Edge Function ouverte à tous qui utilise la clé secrète équivaut à une table sans règle
5. Fais l'inventaire des clés actives dans le tableau de bord, anciennes comprises

Un exemple concret

Une app de gestion de stock construite avec Bolt affiche le tableau de bord des fournisseurs. La règle RLS empêche un fournisseur de voir les commandes d'un autre, et l'écran récapitulatif de l'administrateur reste vide. La correction proposée remplace la clé publique par la clé service_role dans le client du navigateur. L'écran se remplit.

Six mois plus tard, un fournisseur curieux ouvre les outils de développement de son navigateur, copie la clé et peut lire, modifier ou supprimer toutes les données. La bonne correction aurait pris une heure : une règle RLS dédiée au rôle administrateur, ou une fonction serveur qui calcule le récapitulatif. Le Scan de vibebusters cherche précisément ce type de raccourci, dans le code actuel et dans son historique.

Les erreurs les plus fréquentes

• La clé secrète dans le client Supabase du navigateur, pour contourner une règle
• L'ancienne clé service_role jamais désactivée après le passage aux nouvelles clés
• La clé dans un fichier .env versionné sur GitHub, parfois dans un dépôt public
• Une Edge Function sans contrôle d'appelant qui utilise la clé secrète
• La même clé partagée entre l'environnement de test et la production

Ce qu'il faut retenir

La clé secrète est un outil légitime et souvent nécessaire. Elle se gère comme la clé d'un coffre : un seul endroit, côté serveur, avec une liste claire des fonctions qui l'utilisent et un plan pour la remplacer. Le Scan dresse cet inventaire et, si une clé a circulé, l'Intervention organise son remplacement sans interrompre l'app.