Les secrets

Une clé d’API donne accès à un service payant ou à tes données : elle ne doit jamais se retrouver dans le code du site, ni dans une conversation. Highwind range ces clés dans les secrets du projet : chiffrées, lues seulement par le serveur de ton app, et jamais montrées à l’agent.

Quand l’agent a besoin d’une clé

Quand une fonction a besoin d’une clé que ton projet n’a pas encore (envoyer des e-mails avec Resend, appeler OpenAI, encaisser avec Stripe…), l’agent ne te la demande pas dans le chat. Il fait apparaître une carte sous sa réponse, et l’étape « Demande la clé RESEND_API_KEY » dans le fil.

1. Lis la carte. Elle s’intitule L’agent a besoin d’une clé (ou L’agent a besoin de ta connexion Resend pour un connecteur) et explique en une phrase à quoi sert la clé et où la trouver.

2. Récupère la clé sur le site du service (par exemple resend.com → API Keys).

3. Colle-la dans le champ masqué (Colle la valeur ici), puis clique sur Ajouter. La mention Chiffrée, jamais montrée à l’agent te rappelle que l’agent ne verra jamais la valeur.

4. Pour un connecteur, Highwind teste la clé auprès du service : « Clé Resend vérifiée : elle fonctionne. », ou un message si le service la refuse ou ne répond pas.

L’agent n’attend pas ta clé pour avancer : il écrit tout de suite le code qui la lit, fait répondre une erreur claire tant qu’elle manque, et te précise dans son résumé que la fonction marchera dès que la clé sera ajoutée. Une fois la clé ajoutée, la fonction marche dans l’aperçu sans autre action.

Une clé déjà enregistrée dans ton compte ?

Pour un connecteur, si tu as déjà enregistré une clé de ce service dans ton compte, la carte propose Utiliser une connexion de ton compte : un clic suffit, sans recoller la clé. Sinon, une nouvelle clé collée dans la carte est chiffrée et enregistrée dans ton compte, réutilisable dans tes autres projets.

Si tu ne veux pas fournir la clé maintenant, clique sur Ignorer : la demande disparaît, et la fonction concernée continue de répondre une erreur claire.

Jamais de clé dans le chat

Ne colle jamais une clé d’API dans un message à l’agent : elle serait enregistrée dans la conversation. Utilise toujours la carte, ou Paramètres du projet → Secrets.

Où vont tes secrets

• Chiffrés en base de données, et jamais renvoyés par Highwind une fois enregistrés : pour changer une valeur, tu la remplaces.
• Jamais montrés à l’agent : il voit seulement le nom des secrets qui existent (par exemple RESEND_API_KEY), jamais leur valeur. Les fichiers qui les contiennent dans l’aperçu (.env.local, .dev.vars) lui sont cachés, comme dans l’onglet Code, et ne font pas partie des versions ni du code téléchargé.
• Lus uniquement par le serveur de ton app (worker/index.ts), dans l’aperçu comme une fois publiée. Ils n’arrivent jamais dans le navigateur de tes visiteurs.
• Appliqués tout de suite : un secret ajouté, remplacé ou supprimé est pris en compte dans l’aperçu, et aussi dans l’app publiée, sans republier.

Pour aller plus loin : lire un secret dans le serveur

Le serveur déclare ses secrets dans l’interface Env de worker/index.ts, puis les lit avec env.NOM :

worker/index.ts (extrait)

export interface Env {
  OPENAI_API_KEY: string;
}

// dans une route :
if (!env.OPENAI_API_KEY) return json({ error: "Clé OpenAI pas encore ajoutée" }, 503);

Un secret n’est jamais lu dans le code du front (src/) : tout ce qui y est écrit est visible par n’importe quel visiteur.

Les valeurs publiques

Certaines valeurs demandées par un connecteur ne sont pas secrètes : un identifiant de mesure Google Analytics (G-…), par exemple, est de toute façon visible dans le code de n’importe quel site qui l’utilise. Ces champs sont marqués public dans les formulaires et affichés en clair. L’agent reçoit leur valeur et peut l’écrire dans le code du navigateur. Tous les autres champs restent des secrets.

Gérer les secrets du projet

Ouvre Paramètres du projet (l’engrenage dans l’en-tête de l’éditeur), puis la section Secrets.

Action	Comment
Voir les secrets	La liste Secrets du projet affiche leurs noms, la date de modification, et Demandé par l’agent pour ceux qui attendent encore une valeur.
Ajouter un secret toi-même	Nouveau secret : un nom, une valeur, puis Ajouter.
Changer une clé	Remplacer, puis colle la nouvelle valeur. L’ancienne n’est jamais réaffichée.
Supprimer un secret	Supprimer. Les routes qui l’utilisent répondront une erreur jusqu’à ce qu’il soit ajouté de nouveau.
Clé fournie par une connexion de ton compte	Elle apparaît avec Via la connexion « … ». Délier retire le lien avec ce projet, sans supprimer la connexion de ton compte.

Règles pour le nom d’un secret :

• majuscules, chiffres et _, en commençant par une lettre (par exemple RESEND_API_KEY) ;
• les préfixes HIGHWIND_, CF_, CLOUDFLARE_ et VITE_ sont réservés ;
• jusqu’à 50 secrets par projet, et 5 Ko par valeur.

Astuce

Une clé refusée par le service ? La carte affiche « Resend a refusé cette clé ». Vérifie-la, puis remplace-la dans Paramètres du projet → Secrets. Pour un connecteur, la section Connecteurs des paramètres du projet propose aussi Tester la clé.

Relier une connexion enregistrée dans ton compte

Les clés des connecteurs peuvent être enregistrées une fois dans ton compte, puis reliées à plusieurs projets. Tu peux même en garder plusieurs pour un même service (une clé de test et une clé de production, par exemple).

1. Ouvre la page Connecteurs depuis la barre latérale de Highwind pour voir et ajouter tes connexions.

2. Dans un projet, ouvre Paramètres du projet → Connecteurs et clique sur Utiliser à côté de la connexion voulue. Ou choisis-la directement dans la carte de l’agent (Utiliser une connexion de ton compte).

3. Le projet utilise désormais cette clé. Si tu la remplaces dans ton compte, tous les projets reliés reçoivent la nouvelle.

Voir Connexions du compte.

Voir aussi

Le serveur de l'appLes routes /api qui lisent tes secrets.

Connexions du compteEnregistrer une clé une fois, la relier à plusieurs projets.

ConnecteursLes services que ton app peut appeler.

SécuritéComment Highwind protège tes apps et tes données.