Dentro de n8n, la palabra «clave» designa al menos tres cosas distintas: la clave pública de la API que administra la propia instancia, la clave compatible con OpenAI que llama a los servicios de modelos y la N8N_ENCRYPTION_KEY que protege las credenciales guardadas en la base de datos. Las tres tienen usos diferentes y colocarlas en el lugar equivocado genera problemas de seguridad. Muchas consultas del tipo «la configuración no surte efecto» nacen precisamente de confundir una con otra.

Este artículo sigue el orden «qué es, dónde va, cómo se rota y cómo se diagnostica un problema», y está pensado para equipos que autoalojan n8n y para instancias en las que colaboran varias personas.

Nota: n8n es una marca de n8n GmbH y OpenAI es una marca de OpenAI, Inc. Este artículo es solo una explicación técnica y no implica afiliación ni relación con esas empresas. Los precios y los modelos disponibles se rigen por la página de precios de modelos.

1. Distinga primero las tres claves

Tipo Uso Dónde se guarda Cabecera habitual
Clave pública de la API de n8n Llama a la API REST de n8n y administra flujos y ejecuciones Se crea en la interfaz de n8n y la guarda quien llama X-N8N-API-KEY
Clave del servicio de modelos Llama a la interfaz compatible con OpenAI Credencial de n8n, cifrada en la base de datos Authorization: Bearer ...
N8N_ENCRYPTION_KEY Cifra las credenciales de la base de datos Variable de entorno o archivo de configuración de .n8n No se envía como cabecera

La clave pública de la API no sirve para llamar a modelos, y la clave de modelos no sirve para administrar flujos de n8n. La consecuencia más directa de mezclarlas es un 401, o una ampliación de permisos que deberían haber sido de solo lectura.

2. Cómo crear la clave pública de la API de n8n

La entrada está en Settings > n8n API. Pulsa Create an API key y rellena Label y la fecha de caducidad. La documentación de n8n señala que la prueba gratuita en la nube no permite usar la API pública; la edición Enterprise permite además elegir Scopes y limitar la clave a recursos y acciones concretos, como workflow:read o credential:list. En las ediciones que no son Enterprise, la clave tiene por defecto acceso completo a los recursos de la cuenta, así que conviene controlar todavía más quién la posee.

Al llamar, coloca la clave en la cabecera X-N8N-API-KEY; la ruta suele ser /api/v1:

curl -sS "https://tu-dominio-n8n/api/v1/workflows?active=true" \
  -H "accept: application/json" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Algunas reglas:

  1. Una clave debe servir a un solo propósito, por ejemplo CI, monitoreo o una herramienta interna.
  2. Define una fecha de caducidad y rota la clave antes de que llegue.
  3. No escribas la clave en código de frontend, parámetros de URL ni registros.
  4. No uses la clave pública de la API en lugar de la clave de modelos.
  5. Si no la necesitas, desactiva la API pública con N8N_PUBLIC_API_DISABLED=true.

3. Credenciales de modelos: la clave va en la credencial

Para conectar un servicio compatible con OpenAI, usa una credencial de tipo OpenAI y rellena API Key y Base URL. La dirección de la pasarela suele escribirse hasta /v1, por ejemplo https://ai.zhongshangqihang.com/v1. El Organization ID solo hace falta con cuentas multicorporativas del servicio propio de OpenAI; con una pasarela compatible normalmente se deja vacío. La credencial también admite cabeceras personalizadas, útil cuando la pasarela exige un identificador adicional.

No dejes que la clave aparezca en estos lugares:

  • nodos Code, nodos Set o prompts;
  • campos normales del JSON de un flujo;
  • cuerpos de respuesta de Webhook, registros de ejecución y notificaciones de error;
  • capturas de pantalla, grabaciones de pantalla y documentos compartidos.

La exportación de un flujo normalmente no incluye la credencial en sí, pero una clave escrita en los parámetros de un nodo sí sale junto con el JSON. Antes de compartir un flujo en equipo, busca sk- y los prefijos de clave habituales.

4. Variables de entorno: sirven para configurar, no como almacén de secretos

n8n autoalojado usa variables de entorno para configurar el puerto, la base de datos, la dirección de Webhook y otros parámetros. Los valores sensibles, como N8N_ENCRYPTION_KEY o la contraseña de la base de datos, también deben inyectarse mediante variables de entorno o un gestor de secretos, no escribirse en el archivo Compose y subirse a Git. Algunas variables admiten el sufijo _FILE para leer el valor desde un archivo aparte.

Pero una variable de entorno no es un almacén de secretos seguro. La documentación de n8n advierte que las variables de entorno no están protegidas dentro de n8n y pueden filtrarse a los usuarios; por eso no se recomienda distribuir credenciales en bloque con CREDENTIALS_OVERWRITE_DATA. Es más prudente usar un endpoint de sobrescritura con autenticación.

Si permites que personal de negocio edite flujos, conviene activar N8N_BLOCK_ENV_ACCESS_IN_NODE=true para impedir que las expresiones y los nodos Code lean variables de entorno. El valor predeterminado es false y, tras cambiarlo, hay que reiniciar la instancia. Ten en cuenta además que el historial de ejecución guarda entradas y salidas de los nodos: anonimiza los campos sensibles antes de que lleguen a n8n o reduce la retención con EXECUTIONS_DATA_MAX_AGE.

5. Clave de cifrado: si se pierde, ninguna credencial se puede leer

En el primer arranque, n8n genera automáticamente una clave de cifrado, la guarda en el directorio ~/.n8n y la usa para cifrar las credenciales que se escriben en la base de datos. También puedes fijar un valor propio con N8N_ENCRYPTION_KEY. La documentación de n8n lo dice con claridad: si se pierde esta clave, todas las credenciales guardadas dejan de poder leerse.

Por eso las copias de seguridad deben hacerse en pareja: la base de datos y la clave de cifrado se guardan por separado y con accesos independientes. Si solo respaldas la base de datos, al restaurar no tendrás la clave original y las credenciales seguirán sin abrirse; si solo respaldas la clave, la base de datos perdida no sirve de nada.

En modo cola, la instancia principal y todos los workers deben usar el mismo N8N_ENCRYPTION_KEY; de lo contrario, los workers no podrán descifrar las credenciales que escribe la instancia principal. Antes de escalar, deja este punto escrito en la lista de despliegue.

Desde n8n 3.0 existe soporte predeterminado para la rotación de la clave de cifrado de datos; en 2.x hay que activar N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true manualmente y mantener el mismo valor en todos los nodos. Antes de rotar, haz una copia completa de la base de datos; la documentación también advierte que, tras habilitar el formato nuevo, no se debe volver a una versión anterior. La entrada de rotación está en Settings > Data Encryption Keys.

6. Rotación y mínimo privilegio

La gestión de claves no consiste en configurarlas una vez y olvidarse, sino en reducir permisos de forma continua:

  • Por entorno: desarrollo, pruebas y producción usan claves distintas; la clave de producción no se guarda en la máquina de desarrollo.
  • Por proyecto: una clave por proyecto, con consumo y cuota observados por separado.
  • Por persona: cada persona tiene su propia clave y se revoca de forma individual al salir, sin claves compartidas por todo el equipo.
  • Caducidad corta: define fecha de caducidad para la clave pública de la API y rota también las claves de modelos con regularidad.
  • Crear antes de borrar: al rotar, crea la clave nueva, actualiza los llamadores, valida y después revoca la antigua.
  • Mínimo privilegio: en la clave pública de la API de Enterprise, marca solo los scopes necesarios; en los roles de proyecto, concede únicamente los permisos requeridos.
  • Limitar el uso: algunas credenciales basadas en la API web permiten configurar los dominios HTTP permitidos, lo que reduce el riesgo de que la clave se use contra otras direcciones.
  • Auditoría: conserva registros de creación, uso y borrado de claves, y alerta ante consumos anómalos.

7. Roles de equipo y credenciales compartidas

Los roles de instancia de n8n incluyen Owner, Admin y Member, y los proyectos y credenciales pueden aislarse por proyecto. En la edición Community, las credenciales viven en el espacio personal; las versiones que admiten proyectos permiten colocarlas en un proyecto para que las use el equipo. Los roles personalizados y los permisos granulares de nivel empresarial pertenecen a la edición Enterprise; consulta la documentación para conocer el alcance exacto.

Recomendaciones prácticas:

  1. Deja el rol Owner en pocas manos y usa Admin o Member para el trabajo diario.
  2. Coloca los flujos de negocio en proyectos y las credenciales también en proyectos, no en espacios personales.
  3. Nombra las credenciales con el patrón «servicio-entorno-uso», por ejemplo «pasarela-producción-resumen-atención».
  4. No compartas cuentas de acceso ni envíes claves personales a compañeros.
  5. Activa MFA, fuerza HTTPS en producción y configura N8N_SECURE_COOKIE=true.
  6. En producción, usa un task runner externo; la documentación ya marca el modo internal como no recomendado y lo declara obsoleto desde 3.0.

La edición Enterprise también permite usar un almacén externo de secretos y referenciar valores de 1Password Connect, AWS Secrets Manager, Azure Key Vault, GCP Secrets Manager, HashiCorp Vault o Infisical en los campos de una credencial. La referencia se resuelve solo dentro de ese campo y no aparece en otras expresiones del flujo.

8. Diagnóstico de problemas frecuentes

Síntoma Causa posible Solución
Las credenciales no se pueden descifrar Se cambió N8N_ENCRYPTION_KEY o se restauró una base de datos antigua Vuelve a la clave original; restaura con la copia correspondiente
La API pública devuelve 401 Falta X-N8N-API-KEY o está caducada Vuelve a crear la clave y revisa la cabecera
La API pública devuelve 403 Scopes insuficientes en Enterprise Añade los scopes necesarios, como workflow:read
La petición al modelo devuelve 401 Clave de modelo incorrecta, caducada o credencial no seleccionada Vuelve a introducir la clave y confirma que la credencial está vinculada al nodo
No se leen las variables de entorno La variable no llega al contenedor o el acceso desde nodos está bloqueado Revisa el entorno de Compose y confirma N8N_BLOCK_ENV_ACCESS_IN_NODE
El worker informa un fallo de descifrado La clave del worker no coincide con la de la instancia principal Unifica N8N_ENCRYPTION_KEY y reinicia

El orden de diagnóstico debería empezar por «qué se cambió últimamente»: cambiar una clave, modificar la Base URL, actualizar la versión o migrar la base de datos son los cuatro cambios que más problemas de claves provocan. Cambia una sola variable a la vez y valida de inmediato con la petición más pequeña posible.

Preguntas frecuentes

¿La clave de la API de n8n y la clave de la API de OpenAI son lo mismo?

No. La clave de la API de n8n sirve para llamar a la API REST del propio n8n y viaja en la cabecera X-N8N-API-KEY; la clave compatible con OpenAI sirve para llamar a la interfaz de modelos, se guarda en una credencial y el nodo la envía como Bearer.

¿La clave pública de la API de n8n admite ámbitos de permiso?

La edición Enterprise admite Scopes y permite limitarla a recursos y acciones concretos; la recomendación es conceder solo el ámbito necesario. En las ediciones que no son Enterprise, la clave tiene acceso completo a los recursos de la cuenta por defecto, así que conviene separarla por persona y por uso, y definir una caducidad.

¿Qué pasa si modifico N8N_ENCRYPTION_KEY?

Las credenciales ya cifradas normalmente dejan de poder descifrarse. En el primer despliegue hay que fijar el valor y respaldarlo; si necesitas cambiarlo, evalúa primero si puedes hacerlo con la función de rotación de claves en lugar de modificar la variable de entorno directamente.

¿Puedo usar variables de entorno para que los flujos lean una clave?

Se puede, pero no es recomendable. La documentación de n8n advierte que las variables de entorno no están protegidas y pueden filtrarse a los usuarios. Es más seguro usar credenciales o un almacén externo de secretos; si no queda otra, activa al menos N8N_BLOCK_ENV_ACCESS_IN_NODE y limita el acceso a la instancia.

¿Está bien que todo el equipo comparta una clave de modelo?

No es aconsejable. Una clave compartida impide separar el consumo, una filtración afecta a todos y no se puede revocar de forma individual. Divide las claves por proyecto, entorno o persona y acompáñalas con las cuotas y los informes de uso de la pasarela; así el costo y la seguridad se controlan mejor.

Siguiente paso

El sistema de claves de n8n se resume en una frase: la clave pública de la API administra la instancia, la clave de modelos gestiona las llamadas y la clave de cifrado protege la base de datos. Guárdalas por separado, rótalas por separado y acompáñalas con roles de proyecto, caducidad y auditoría para completar la configuración. Si necesitas un punto de entrada unificado de modelos y gestión de uso, puedes registrarte en ZSQH AI Gateway; los modelos y los precios se rigen por la página de precios de modelos.

Lecturas relacionadas: