Cuando alguien dice «configura la API Key de Dify», puede estar hablando de cosas completamente distintas: la clave del proveedor que permite a Dify llamar a los modelos, la clave de acceso que usa un sistema externo para llamar a una aplicación de Dify, o la Service API Key de una base de conocimiento. Las tres se crean en lugares diferentes, tienen alcances distintos y, si se filtran, las consecuencias también cambian. El error más común es mezclarlas: pegar la clave de proveedor en el frontend, entregar a un llamador una clave de aplicación con permisos de más o rotar el objeto equivocado y provocar un 401 en toda la línea de producción.

Los nombres de la interfaz y los detalles de permisos pueden cambiar según la versión; guíate por la interfaz actual de tu instancia y su documentación.

Nota: Dify es una marca de su titular, LangGenius, Inc. Este artículo es una explicación técnica independiente y no guarda relación de afiliación ni de representación con el equipo de Dify.

1. Primero, distingue las tres claves

Una tabla ayuda a delimitar las fronteras.

Tipo de clave Para qué sirve Dónde se crea Alcance Quién la gestiona
Clave de proveedor de modelos Dify llama a los modelos upstream Ajustes → Proveedores de modelos → Proveedor correspondiente Todo el espacio de trabajo Owner y Admin
Clave de API de aplicación Un sistema externo llama a una aplicación de Dify Aplicación → Acceso a la API Una sola aplicación, para todos sus usuarios finales Editor o superior
Service Key de base de conocimiento Un sistema externo llama a la API de conocimiento Base de conocimiento → Service API Se puede limitar a bases concretas Editor o superior

Las tres no son intercambiables: la clave de proveedor no sirve para llamar a la API de una aplicación y la clave de aplicación no permite que Dify llame a un modelo. Antes de diagnosticar, confirma cuál tienes en la mano.

2. Clave de proveedor: nivel de espacio de trabajo, la configura el administrador

La clave de proveedor es una configuración del espacio de trabajo. Se añade en los ajustes de proveedores de modelos y Dify la usa para enviar solicitudes al upstream. La plataforma la valida al añadirla y, una vez aprobada, queda disponible para todo el espacio. Solo Owner y Admin pueden gestionarla; Editor y Normal no ven esos ajustes.

Detalles que suelen pasarse por alto:

  • Un proveedor puede guardar varias claves, separadas por desarrollo, producción o cuenta, para identificar la facturación y desactivarlas por separado.
  • Las claves de modelos personalizados se gestionan aparte. Borrar la última clave elimina también el modelo personalizado; si solo borras el modelo, la clave se conserva y no tendrás que volver a introducirla al recrearlo.
  • Professional y Team admiten varias claves por modelo con balanceo de carga. Cuando una clave alcanza su límite, la plataforma la omite durante un minuto.
  • Si Cloud incluye AI credits, puedes no configurar una clave de proveedor; también pueden convivir ambas opciones y decidir con Usage Priority cuál se usa primero. Con tu propia clave, el costo se registra en tu cuenta de proveedor.

Conviene nombrar las claves con el esquema «uso-entorno-responsable»; el panel del proveedor suele mostrar el consumo de cada clave, lo que facilita localizar anomalías.

3. Clave de API de aplicación: solo en el backend

La clave de aplicación resuelve otro problema: cómo llama un sistema externo a una aplicación ya publicada. No participa en la selección de modelos ni sirve para llamar a la API de modelos. El flujo típico es el siguiente.

  1. Abre la aplicación de destino y entra en la página de acceso a la API.
  2. Crea una clave y nómbrala con «llamador-entorno-fecha».
  3. Cópiala a las variables de entorno del servidor o a un gestor de secretos; no la escribas en el frontend, el repositorio ni un chat.
  4. Llama primero a GET /info para verificar que la clave corresponde a la aplicación.
  5. Después llama al endpoint que corresponda al tipo de aplicación; cada tipo tiene su propia interfaz.
  6. Al publicar, registra la aplicación a la que pertenece la clave, el responsable y la fecha de creación.
# Dirección base de Dify Cloud; en autoalojado, usa la de tu instancia
export DIFY_BASE_URL="https://api.dify.ai/v1"
export DIFY_APP_KEY="tu clave de aplicación"

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

Si devuelve el nombre, el modo y la descripción de la aplicación, la clave es válida. Hay dos puntos que conviene recordar: una clave de aplicación afecta a todos los usuarios finales de esa aplicación, y en cada llamada se distingue al usuario con el campo user del cuerpo, aunque user solo es un identificador y no un mecanismo de autenticación; además, la API de aplicación debe llamarse desde el backend, y la documentación desaconseja expresamente colocar la clave en el frontend o en el código del cliente.

4. Service Key de conocimiento: limita el alcance siempre que puedas

La base de conocimiento tiene su propia Service API Key, en la página Service API, y no se comparte con la clave de aplicación. Al crearla puedes limitar a qué bases de conocimiento puede acceder; una clave con acceso a todas las bases también puede llamar al endpoint que las lista.

La práctica de mínimo privilegio consiste en crear una clave por consumidor y marcar solo las bases necesarias, en lugar de usar una clave global para todos los llamadores. Si se filtra una clave de conocimiento, los datos pueden leerse o escribirse, no solo se consume cuota de modelo; el riesgo es mayor.

5. Dónde viven las claves: .env, SECRET_KEY y cifrado del espacio

En un despliegue autoalojado, las claves se reparten en dos capas, y mucha gente solo cambia la primera.

La primera capa es docker/.env, copiado de .env.example; la configuración de la raíz sobrescribe los valores con el mismo nombre de docker/envs/*.env. La variable que más se pasa por alto es SECRET_KEY: participa en la firma de cookies de sesión y JWT, en la firma HMAC-SHA256 de las URL de archivos y en el cifrado AES-256 de las credenciales OAuth de terceros. El valor de ejemplo debe sustituirse; puedes generarlo con openssl rand -base64 42.

Cambiar SECRET_KEY cierra la sesión de todos los usuarios, invalida las URL de archivos ya emitidas y hace irrecuperables las credenciales OAuth cifradas con el valor anterior. No es una rotación rutinaria: antes de tocarla, evalúa el impacto y haz una copia de seguridad.

La segunda capa es el cifrado de credenciales del espacio de trabajo. Las claves de proveedor y las credenciales de herramientas se cifran con la clave RSA de cada espacio, y la clave privada se guarda en el backend indicado por STORAGE_TYPE. KEY_PROVIDER_TYPE es local por defecto, pero también puede conectarse a Azure Key Vault con rotación automática. Esta opción debe decidirse antes de crear el primer espacio de trabajo: los dos métodos producen cifrados incompatibles y, si se cambia a mitad de camino, las credenciales existentes no se pueden descifrar y hay que volver a introducirlas.

Las versiones más recientes incluyen DIFY_AGENT_SERVER_SECRET_KEY y DIFY_AGENT_API_TOKEN en la configuración del agente; los valores predeterminados de desarrollo son públicos y deben sustituirse antes de publicar. No subas .env al repositorio y restringe los permisos del archivo según la documentación; incluye el material de claves en las copias de seguridad, porque de lo contrario las credenciales pueden quedar inservibles al restaurar el entorno.

En Cloud, las credenciales de proveedor las gestiona la plataforma y no tienes que administrar SECRET_KEY, pero aun así conviene usar cuentas o claves de proyecto independientes y conservar el registro del lado del proveedor.

6. Rotación, mínimo privilegio y roles del equipo

La rotación no se hace solo cuando hay una filtración. Conviene realizarla cuando alguien deja el equipo, cambia un llamador, hay sospecha de filtración, lo exige el proveedor o llega una revisión periódica. El proceso completo es el siguiente.

  1. Crea en el proveedor o en Dify una clave nueva con los mismos permisos y mantenla en paralelo con la anterior.
  2. Escribe la clave nueva en el gestor de secretos o en las variables de entorno y publica la configuración.
  3. Observa durante un tiempo la tasa de errores, el volumen de llamadas y la factura del proveedor para confirmar que el tráfico ya migró.
  4. Desactiva la clave antigua; no te limites a borrarla de la configuración.
  5. Registra la fecha de rotación, quién la ejecutó y el alcance, y actualiza el documento de traspaso.

En cuanto a los roles, el espacio de trabajo se organiza aproximadamente así: Owner tiene todo el control y solo hay uno; Admin gestiona miembros y proveedores; Editor puede crear, editar y eliminar aplicaciones y bases de conocimiento; Normal solo usa aplicaciones publicadas. La regla puede ser sencilla: las claves de proveedor quedan solo en manos de Owner y Admin; las claves de aplicación se entregan al responsable del backend correspondiente; las claves de conocimiento se dividen por consumidor y se limitan a un alcance concreto. Editor puede modificar aplicaciones y normalmente también accede a su clave de API, así que no conviene equiparar «puede editar aplicaciones» con «puede gestionar las claves de modelo de toda la empresa».

7. Errores frecuentes y diagnóstico

Al diagnosticar, confirma primero el tipo de clave y después revisa la red y los permisos.

  • 401 (credenciales rechazadas): la clave está mal escrita, fue revocada, lleva espacios o saltos de línea de más, o se está usando una clave de proveedor como clave de aplicación. Repite la prueba con GET /info.
  • 403 o permisos insuficientes: el rol no alcanza, o la clave de conocimiento no incluye la base de destino.
  • 404 Not Found: la Base URL no es correcta. Cloud usa https://api.dify.ai/v1; el autoalojado termina en tu dominio más /v1, sin la ruta completa del endpoint.
  • La API indica que el modelo no está disponible: la clave de proveedor caducó, no tiene saldo o el upstream aplica límites de tasa; vuelve a validarla en los ajustes de proveedores.
  • 404/403 en la API de conocimiento: se mezclaron la clave de aplicación y la Service Key, o la base no está dentro del alcance de la clave.
  • 429 Too Many Requests: se activó el límite de tasa. Reduce la concurrencia y reintenta con retroceso exponencial.
  • Todos los usuarios desconectados tras cambiar SECRET_KEY: es el comportamiento esperado, como se explicó antes; evalúa el impacto y no vuelvas sin más al valor anterior.

Otro error habitual: Dify está desplegado en un contenedor o en la nube, pero se configura con localhost o una dirección de red interna. Dify no puede alcanzar tu servicio local y la clave correcta no sirve de nada. Si un sistema de negocio no conecta con un Dify autoalojado, revisa primero DNS, firewall, proxy inverso y certificados.

Preguntas frecuentes

¿Se pueden intercambiar la clave de proveedor y la clave de aplicación?

No. La primera permite que Dify llame a los modelos upstream; la segunda permite que un sistema externo llame a una aplicación de Dify. Los endpoints, los permisos y el objeto de facturación son distintos.

¿Una aplicación puede tener varias API Keys?

Normalmente sí. Lo habitual es separarlas por entorno o por llamador para poder desactivarlas y rastrearlas por separado. La entrada concreta depende de la interfaz de la versión actual.

¿La clave de aplicación puede limitarse a una base de conocimiento o a un usuario?

La granularidad de la clave de aplicación es la aplicación y no se puede dividir por base de conocimiento; el campo user solo distingue usuarios finales y no es un mecanismo de autenticación. Si necesitas limitar por base, usa una Service API Key y marca el alcance.

¿Cambiar SECRET_KEY afecta las claves de proveedor?

Las credenciales de proveedores y herramientas se cifran con la clave RSA del espacio de trabajo, no directamente con SECRET_KEY; aun así, al cambiarla los usuarios se desconectan, las URL de archivos se invalidan y las credenciales OAuth no se pueden recuperar. Antes de modificarla en producción, lee la documentación de despliegue y haz una copia de seguridad.

Tras actualizar el autoalojado, las claves dejan de funcionar. ¿Qué reviso primero?

Compara .env.example con tu .env para detectar variables nuevas y confirma que KEY_PROVIDER_TYPE y el backend de almacenamiento no cambiaron; si se cambió el método de cifrado, las credenciales antiguas no se descifran y hay que volver a introducirlas. Por último, revisa el código de error en los logs de la aplicación.

Siguiente paso

La gestión de claves en Dify se resume en tres frases: distingue el tipo, emite con mínimo privilegio y trata la rotación como un proceso fijo. Si necesitas una entrada unificada compatible con OpenAI y centralizar las llamadas a modelos, puedes registrarte en ZSQH AI Gateway; el catálogo y los precios se rigen por la página de precios de modelos.

Lecturas relacionadas: