Quand on dit « configurer la clé API de Dify », il peut s'agir de choses totalement différentes : parfois la clé fournisseur qui permet à Dify d'appeler un modèle, parfois la clé d'accès qu'un système métier utilise pour appeler une application Dify, parfois encore la clé Service API d'une base de connaissances. Les trois se créent à des endroits différents, ont des portées différentes et des conséquences différentes en cas de fuite. Les confondre conduit le plus souvent à mettre une clé fournisseur dans un front-end, à remettre à un appelant une clé d'application trop permissive, ou à faire tourner le mauvais objet et provoquer des 401 en production.

Les noms d'interface et les détails de permission peuvent changer selon les versions : référez-vous à l'interface et à la documentation de votre instance.

Remarque : Dify est une marque de LangGenius, Inc. Cet article est une présentation technique indépendante, sans affiliation ni mandat avec l'équipe Dify.

1. Distinguer les trois types de clés

Commençons par un tableau qui fixe les frontières.

Type de clé Rôle Où la créer Portée Qui peut la gérer
Clé fournisseur Dify appelle le modèle amont Paramètres → fournisseurs → fournisseur concerné Partagée par tout l'espace de travail Owner, Admin
Clé d'application Un système externe appelle une application Dify Application → accès API Une application, tous ses utilisateurs finaux Editor et au-dessus
Clé Service de base de connaissances Un système externe appelle l'API de la base Base de connaissances → Service API Peut être limitée à certaines bases Editor et au-dessus

Les trois ne sont pas interchangeables : une clé fournisseur ne peut pas appeler l'interface d'une application, et une clé d'application ne permet pas à Dify d'appeler un modèle. Avant de diagnostiquer, identifiez le type que vous avez en main.

2. Clé fournisseur : au niveau de l'espace de travail, configurée par un administrateur

La clé fournisseur est une configuration d'espace de travail, ajoutée dans les paramètres du fournisseur de modèles ; Dify l'utilise pour adresser les requêtes de modèles à l'amont. La plateforme la valide à l'ajout, puis elle est disponible pour tout l'espace. Seuls Owner et Admin peuvent la gérer ; Editor et Normal ne voient pas ces paramètres.

Quelques détails souvent négligés :

  • Un fournisseur peut conserver plusieurs clés, séparées par développement, production ou compte, pour faciliter l'imputation des factures et la désactivation ciblée.
  • Les clés des modèles personnalisés sont gérées à part. Supprimer la dernière clé supprime aussi le modèle personnalisé ; supprimer seulement le modèle conserve la clé, à ressaisir lors d'un nouvel ajout.
  • Professional et Team prennent en charge l'équilibrage entre plusieurs clés pour un même modèle. Quand une clé atteint sa limite, la plateforme l'ignore pendant une minute.
  • Quand le Cloud fournit des crédits IA, vous pouvez ne pas configurer de clé fournisseur ; les deux peuvent coexister, et Usage Priority détermine la priorité. Avec votre propre clé, les frais sont imputés à votre compte fournisseur.

Nommez les clés selon « usage-environnement-responsable » : le back-office du fournisseur affiche généralement l'usage par clé, ce qui facilite le diagnostic en cas d'anomalie.

3. Clé d'application : uniquement côté backend

La clé d'application répond à une autre question : comment un système externe appelle une application déjà publiée. Elle n'intervient pas dans le choix du modèle et ne peut pas appeler l'interface des modèles. Le flux typique :

  1. Ouvrez l'application cible et sa page d'accès API.
  2. Créez une clé nommée « appelant-environnement-date ».
  3. Copiez-la dans une variable d'environnement serveur ou un service de secrets, jamais dans un front-end, un dépôt ou une conversation.
  4. Appelez d'abord GET /info pour vérifier que la clé correspond à l'application.
  5. Appelez ensuite l'interface adaptée au type d'application, chaque type ayant la sienne.
  6. Après mise en production, consignez l'application, le responsable et la date de création.
# Adresse de base de Dify Cloud ; remplacez-la par votre instance en auto-hebergement
export DIFY_BASE_URL="https://api.dify.ai/v1"
export DIFY_APP_KEY="votre-cle-d-application"

curl "$DIFY_BASE_URL/info" \
  -H "Authorization: Bearer $DIFY_APP_KEY"

Une réponse contenant le nom, le mode et la description de l'application confirme la validité de la clé. Deux points à retenir : une clé d'application vaut pour tous les utilisateurs finaux de cette application ; le champ user du corps distingue les utilisateurs, mais n'est qu'un identifiant, pas une authentification. Par ailleurs, l'API d'application doit être appelée depuis le backend : la documentation déconseille explicitement de placer la clé dans un front-end ou du code client.

4. Clé Service de base de connaissances : limiter la portée quand c'est possible

Les bases de connaissances disposent d'une clé Service API distincte, créée dans leur page Service API, non partagée avec les clés d'application. À la création, vous pouvez limiter les bases auxquelles la clé accède ; une clé couvrant toutes les bases peut aussi appeler l'interface de listage.

La pratique du moindre privilège consiste à créer une clé par consommateur, en ne cochant que les bases nécessaires, plutôt qu'une clé globale pour tous les appelants. Une fuite de clé de base signifie que des données peuvent être lues ou écrites, pas seulement que du quota de modèle est consommé : le risque est plus élevé.

5. Où sont stockées les clés : .env, SECRET_KEY et chiffrement de l'espace de travail

En auto-hébergement, les secrets se répartissent en deux couches ; beaucoup n'en modifient qu'une.

La première est docker/.env, copié depuis .env.example ; la configuration à la racine écrase les variables de même nom dans docker/envs/*.env. SECRET_KEY est le plus souvent négligé : il intervient dans la signature des cookies de session et des JWT, la signature HMAC-SHA256 des URL de fichiers et le chiffrement AES-256 des identifiants OAuth tiers. La valeur d'exemple doit être remplacée ; générez-la avec openssl rand -base64 42.

Changer SECRET_KEY déconnecte tous les utilisateurs, invalide les URL de fichiers déjà émises et rend irrécupérables les identifiants OAuth chiffrés avec l'ancienne valeur. Ce n'est pas une rotation courante : évaluez l'impact et sauvegardez avant modification.

La seconde couche est le chiffrement des identifiants d'espace de travail. Les clés fournisseur et identifiants d'outils sont chiffrés par une clé RSA propre à chaque espace, dont la clé privée réside dans le backend indiqué par STORAGE_TYPE. KEY_PROVIDER_TYPE vaut local par défaut, mais peut pointer vers Azure Key Vault avec rotation automatique. Ce choix doit être fait avant la création du premier espace de travail : les chiffrements des deux modes sont incompatibles, et un changement en cours de route rend les identifiants existants indéchiffrables, à ressaisir entièrement.

Les versions récentes comportent aussi DIFY_AGENT_SERVER_SECRET_KEY et DIFY_AGENT_API_TOKEN dans la configuration des agents ; leurs valeurs de développement sont publiques et doivent être remplacées avant la mise en production. Ne commitez pas .env, resserrez ses permissions selon la documentation et incluez les matériaux de clé dans les sauvegardes, sinon les identifiants peuvent être perdus après restauration.

Sur le Cloud, les identifiants fournisseur sont hébergés par la plateforme et SECRET_KEY n'est pas à gérer ; utilisez néanmoins des comptes ou clés de projet dédiés et conservez les traces côté fournisseur.

6. Rotation, moindre privilège et rôles d'équipe

La rotation ne se fait pas seulement en cas de fuite. Prévoyez-la lors des départs, des changements d'appelant, d'une fuite suspectée, à la demande du fournisseur et lors des contrôles périodiques. Procédure complète :

  1. Créez chez le fournisseur ou dans Dify une nouvelle clé aux mêmes permissions, d'abord en parallèle de l'ancienne.
  2. Écrivez la nouvelle clé dans le service de secrets ou les variables, puis publiez la configuration.
  3. Observez un temps le taux d'erreur, le volume d'appels et la facture fournisseur pour confirmer le basculement.
  4. Désactivez l'ancienne clé, au lieu de la retirer seulement de la configuration.
  5. Consignez la date, l'opérateur et le périmètre, et mettez à jour la documentation de passation.

Les rôles d'espace de travail sont approximativement : Owner détient tout le contrôle et est unique ; Admin gère membres et fournisseurs ; Editor crée, modifie et supprime applications et bases ; Normal utilise seulement les applications publiées. Une règle simple : les clés fournisseur restent entre les mains des Owner et Admin ; les clés d'application vont aux responsables backend ; les clés de base sont découpées par consommateur et limitées. Un Editor pouvant modifier une application peut généralement accéder à sa clé API : « pouvoir éditer une application » ne signifie pas « pouvoir gérer les clés de modèles de toute l'entreprise ».

7. Erreurs courantes et diagnostic

Vérifiez d'abord le type de clé, puis le réseau et les permissions.

  • 401 Unauthorized : clé mal saisie, révoquée, avec espaces ou retours à la ligne parasites, ou clé fournisseur utilisée comme clé d'application. Retestez avec GET /info.
  • 403 ou permissions insuffisantes : rôle insuffisant, ou clé de base qui n'inclut pas la base cible.
  • 404 Not Found : Base URL incorrecte. Le Cloud utilise https://api.dify.ai/v1 ; en auto-hébergement, votre domaine suivi de /v1, sans le chemin complet de l'interface.
  • Modèle indisponible : clé fournisseur expirée, solde insuffisant ou limitation amont ; revalidez dans les paramètres du fournisseur.
  • 404/403 sur l'API de base : clé d'application et clé Service confondues, ou base hors du périmètre de la clé.
  • 429 Too Many Requests : limitation de débit. Réduisez la concurrence et relancez avec un backoff exponentiel.
  • Déconnexion collective après changement de SECRET_KEY : comportement attendu, voir la section précédente ; évaluez l'impact avant de revenir à l'ancienne valeur.

Autre erreur fréquente : Dify est déployé dans un conteneur ou dans le cloud, mais on renseigne localhost ou une adresse interne. Dify ne peut pas atteindre votre service local, quelle que soit la clé. Si un système métier ne joint pas une instance Dify auto-hébergée, vérifiez DNS, pare-feu, reverse proxy et certificats.

FAQ

Clé fournisseur et clé d'application sont-elles interchangeables ?

Non. La première sert à Dify pour appeler le modèle amont, la seconde à un système externe pour appeler une application Dify. Interfaces, permissions et objets facturés diffèrent.

Une application peut-elle avoir plusieurs clés API ?

Généralement oui. La pratique courante est d'en créer par environnement ou par appelant, pour désactiver et tracer séparément. L'entrée exacte dépend de l'interface de votre version.

Une clé d'application peut-elle être limitée à une base ou à un utilisateur ?

La granularité de la clé d'application est l'application ; elle ne se découpe pas par base. Le champ user distingue les utilisateurs finaux mais n'est pas un mécanisme d'authentification. Pour limiter par base, utilisez une clé Service API avec le périmètre adéquat.

Changer SECRET_KEY affecte-t-il les clés fournisseur ?

Les identifiants fournisseur et d'outils sont chiffrés par la clé RSA de l'espace de travail, pas directement par SECRET_KEY ; mais le changement déconnecte les utilisateurs, invalide les URL de fichiers et rend les identifiants OAuth irrécupérables. Lisez la documentation de déploiement et sauvegardez avant toute modification en production.

Après une mise à jour auto-hébergée, les clés ne fonctionnent plus : que vérifier ?

Comparez d'abord .env.example et votre .env pour repérer de nouvelles variables, puis vérifiez que KEY_PROVIDER_TYPE et le backend de stockage n'ont pas changé ; si le mode de chiffrement a changé, les anciens identifiants sont indéchiffrables et doivent être ressaisis. Consultez enfin les codes d'erreur dans les journaux de l'application.

Pour aller plus loin

La gestion des clés Dify se résume en trois phrases : distinguer les types, délivrer selon le moindre privilège, traiter la rotation comme un processus régulier. Pour un point d'entrée compatible OpenAI unifié et une gestion centralisée des appels de modèles, vous pouvez créer un compte sur la passerelle AI de ZSQH ; le catalogue et les prix sont sur la page Tarifs des modèles.

Lectures associées :