Who this is for: DevOps or platform engineers who run n8n in a multi‑node, production environment and need a reliable way to store and rotate API keys, passwords, and other secrets. We cover this in detail in the Production‑Grade n8n Architecture.
Quick Diagnosis
Problem: You need a way to store API keys, passwords, and other secrets safely across multiple n8n workers without exposing them in plain text or risking sync‑drift.
One‑line answer: Use n8n’s built‑in Encrypted Secrets (via the N8N_ENCRYPTION_KEY env var) plus a central secret store—HashiCorp Vault, AWS Secrets Manager, or Docker Swarm/Kubernetes Secrets. Then configure each worker to load the encrypted value at runtime.
In production we often see this break when a new node is added without copying the key.
Docker‑Compose starter (service definition)
services:
n8n:
image: n8nio/n8n:latest
environment:
- N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
Docker‑Compose starter (volume definition)
volumes:
- n8n_data:/home/node/.n8n
volumes:
n8n_data:
Store N8N_ENCRYPTION_KEY and any external‑store tokens in your orchestrator’s secret mechanism (Docker Swarm, k8s, etc.).
1. Why Default n8n Secrets Aren’t Enough for Distributed Deployments?
If you encounter any microservices n8n integration resolve them before continuing with the setup.
| Feature | Single‑node n8n (default) | Distributed n8n (≥2 workers) |
|---|---|---|
| Secret persistence | `.n8n/.env` (plain text) or UI‑saved encrypted with local key | Each node must share identical N8N_ENCRYPTION_KEY; otherwise secrets cannot be decrypted on other workers |
| Rotation overhead | Manual edit + restart | Must propagate new key to all nodes before rotating stored secrets |
| Auditability | None | No built‑in versioning or access logs |
EEFA note: Relying solely on UI‑saved encrypted secrets creates a *single point of failure*—if one worker loses the key, all encrypted credentials become unusable across the cluster.
2. Prerequisites – What You Need Before You Start?
| Requirement | Recommended Tool | Minimal Version |
|---|---|---|
| Central secret store | HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or Kubernetes Secrets | Vault 1.9+, AWS Secrets Manager 2023‑01+ |
| Secure key distribution | Docker Swarm secrets, Kubernetes Secret objects, or Ansible Vault |
Docker 20.10+, k8s 1.22+ |
| n8n version | n8nio/n8n:latest (or ≥1.15 where N8N_ENCRYPTION_KEY is mandatory) |
1.15+ |
| TLS termination | Reverse proxy (Traefik, Nginx) with certs | TLS 1.2+ |
EEFA warning: Never store
N8N_ENCRYPTION_KEYin source control or plain‑text.envfiles that are committed. Use your orchestrator’s secret mechanism.
3. Generating & Distributing the Master Encryption Key
3.1 Create a 32‑byte base64 key
# Linux/macOS openssl rand -base64 32 | tr -d '\n' > n8n_enc_key.txt
3.2 Store the key securely
| Orchestrator | Command / UI |
|---|---|
| Docker Swarm | docker secret create n8n_enc_key n8n_enc_key.txt |
| Kubernetes | kubectl create secret generic n8n-enc-key --from-file=n8n_enc_key.txt |
| Nomad | Add to job template block with sensitive = true |
*It’s easy to miss this on first‑time setups; double‑check the secret actually exists before you spin up workers.*
3.3 Reference the secret in your service definition
Docker‑Compose (Swarm mode) – secret mount
services:
n8n:
secrets:
- n8n_enc_key
Docker‑Compose (Swarm mode) – env var
environment:
- N8N_ENCRYPTION_KEY=/run/secrets/n8n_enc_key
Kubernetes – env var from secret
env:
- name: N8N_ENCRYPTION_KEY
valueFrom:
secretKeyRef:
name: n8n-enc-key
key: n8n_enc_key.txt
EEFA tip: Rotate the master key once per quarter (or after any suspected compromise). Use the
n8n encrypt:rekeyCLI (available in v1.20+) to re‑encrypt all stored secrets without downtime. *Regenerating the key is usually faster than chasing edge cases.*
4. Integrating an External Secret Store
4.1 Choose the provider
| Provider | Pros | Cons |
|---|---|---|
| HashiCorp Vault | Fine‑grained ACLs, dynamic secrets, audit logs | Extra infrastructure |
| AWS Secrets Manager | Managed, IAM‑based access, rotation support | Vendor lock‑in, cost per secret |
| Kubernetes Secrets (sealed‑secrets) | Native to cluster, GitOps‑friendly | Limited to cluster scope |
| Docker Swarm Secrets | Simple for small setups | No built‑in rotation API |
4.2 Pull secrets at runtime – custom credential (part 1)
// credentials/custom-vault-credential.js
const { CredentialBase } = require('n8n-workflow');
const axios = require('axios');
custom credential (part 2) – fetch from Vault
class VaultCredential extends CredentialBase {
async getCredentialData() {
const vaultUrl = process.env.N8N_VAULT_URL;
const token = process.env.N8N_VAULT_TOKEN;
const secretPath = this.getNodeParameter('secretPath');
const resp = await axios.get(`${vaultUrl}/v1/${secretPath}`, {
headers: { 'X-Vault-Token': token },
});
return { apiKey: resp.data.data.api_key };
}
}
module.exports = VaultCredential;
*Add the credential in **Settings → Credentials → New Credential → Custom** and reference secretPath in the node UI.*
4.3 Automatic secret injection via Docker entrypoint – Dockerfile snippet
FROM n8nio/n8n:latest COPY entrypoint.sh /entrypoint.sh ENTRYPOINT ["/entrypoint.sh"]
entrypoint.sh – fetch secret from Vault
#!/bin/sh VAULT_TOKEN=$(cat /run/secrets/vault_token) SECRET=$(curl -s -H "X-Vault-Token: $VAULT_TOKEN" \ https://vault.mycorp.com/v1/secret/data/n8n/api_key | jq -r .data.data.key) export N8N_API_KEY=$SECRET exec "$@"
EEFA caution: The entrypoint runs **before** n8n starts, so the secret is present in the environment but never written to disk.
5. Rotating Secrets Without Service Disruption
5.1 Rotation workflow
- **Create new secret version** in the external store (e.g.,
vault write secret/data/n8n/api_key value=<new>). - **Trigger a rolling restart** of n8n workers (
docker service update --force n8norkubectl rollout restart deployment/n8n). - **Verify** that each node can decrypt existing credentials using the unchanged
N8N_ENCRYPTION_KEY. - **Run
n8n encrypt:rekey** (optional) if you also changed the master key.
*Most teams run into this after a few weeks, not on day one.*
5.2 Sample script for automated rotation – generate new value
#!/usr/bin/env bash set -euo pipefail NEW_VALUE=$(aws secretsmanager get-random-password \ --password-length 32 --exclude-punctuation \ --query 'RandomPassword' --output text) aws secretsmanager put-secret-value \ --secret-id n8n/api_key --secret-string "$NEW_VALUE"
5.3 Sample script – rolling update in Kubernetes
kubectl rollout restart deployment/n8n
EEFA note: Always test rotation in a staging namespace before applying to production. Use the
--dry-run=clientflag inkubectlto preview.
6. Auditing & Monitoring Secrets Usage
| Tool | What it logs | Integration point |
|---|---|---|
| Vault audit device | All read/write operations, client IP | Enable audit device in Vault config |
| AWS CloudTrail | Secrets Manager API calls | Set up CloudWatch alerts for GetSecretValue |
| n8n logs (JSON) | Credential load failures (ERR_CRED_NOT_FOUND) |
Forward to ELK/Datadog for alerting |
| Kubernetes audit logs | Secret mounts, pod exec | Enable --audit-policy-file |
Datadog alert rule (JSON snippet)
{
"query": "logs(\"source:n8n @level:error @msg:ERR_CRED_NOT_FOUND\").rollup('count').by('host') > 5",
"message": "⚠️ Multiple credential load failures on {{host.name}} – check secret store connectivity.",
"tags": ["n8n","security"]
}
7. Best‑Practice Checklist for Distributed n8n Secrets
| Item | Description | Verify |
|---|---|---|
| Master encryption key stored as orchestrator secret | No plain‑text key in repo | docker secret ls / kubectl get secret |
All workers share identical N8N_ENCRYPTION_KEY |
Decryption works cluster‑wide | docker service ps n8n shows same secret version |
| External secret store has least‑privilege policies | Nodes can only read required paths | Vault policy path "secret/data/n8n/*" { capabilities = ["read"] } |
| Secrets are not committed to Docker images | No ENV N8N_API_KEY=... in Dockerfile |
Scan images with Trivy (trivy image n8nio/n8n) |
| Rotation pipeline in CI/CD | Automated, tested, and version‑controlled | GitHub Actions workflow runs rotate-secret.yml on schedule |
| Monitoring alerts for secret fetch failures | Immediate response to outage | Datadog/Prometheus alert active |
| TLS everywhere (ingress, vault, internal API) | Prevent MITM on secret transport | curl -v https://vault.mycorp.com shows TLSv1.3 |
Bottom Line
By centralizing the master encryption key, leveraging a dedicated secret store, and automating rotation with rolling restarts, you achieve a truly distributed, production‑grade secrets management strategy for n8n that eliminates single points of failure and satisfies compliance audits.
