n8n secrets and credential rotation: master key, data key, and every other secret

Conditional verdict — rotation is not one operation

“Rotate the n8n key” is ambiguous. It can mean changing the instance master key, activating a new data-encryption key, replacing a database password, renewing a TLS certificate, or revoking an OAuth refresh token. Each protects a different boundary. Treating them as one action can leave credentials unreadable while a compromised API token remains valid.

Start with an inventory entry for each secret: owner, purpose, issuer or generator, storage location, readers, last verified rotation, backup/escrow reference, revocation behavior, and acceptance test. Never put the actual value in the register. A credential table without the matching master key may be unrecoverable; a key without the database and compatible runtime is not a restore. A plaintext credential export creates another live copy and is not a safe default backup method.

Version is a hard gate. The captured n8n key-rotation documentation describes behavior across 2.x and 3.0, while captured release and migration material has inconsistent early-access/channel labeling around 3.0. Those captures do not establish the exact label or behavior of a later selected build. Before a change, pin the selected image tag and digest, read its matching release notes and migration report, and verify the feature state in that build. Never use an unqualified latest as a rollback plan or casually regenerate N8N_ENCRYPTION_KEY on restart.

This guide is for self-hosted operators who control application configuration and the database. If the owner, backup, key escrow, or downgrade compatibility cannot be demonstrated, stop at inventory and rehearsal. Article 10 owns full restore and migration; Article 4 covers database backup consistency.

Map the stable master key and rotating data key

What the instance master key protects

n8n generates an instance encryption key on first startup and stores it under its .n8n directory, or an operator can configure N8N_ENCRYPTION_KEY. This master key protects encrypted credential data and, when data-key rotation is enabled, protects data keys stored in the database. The same master value must reach every main instance, queue worker, and webhook processor that needs to decrypt shared credentials. It is a stable deployment dependency, not a routine per-container random value.

Keep a protected, independent escrow copy and record its reference, creation/source date, authorized recovery holders, and target instance identity. A fingerprint or vault record ID can help compare references without displaying key material; it cannot substitute for the key during recovery. Store database backups and key escrow with separated access where practical so one accidental disclosure does not hand the same audience both ciphertext and its decryption root. Verify the selected deployment’s actual configuration method and file permissions; do not assume an import command exists for a pre-seeded install.

In queue mode, consistent key distribution is essential: a worker with a different key can fail on credentials the main instance can read. Distribute through the operator’s controlled configuration path, not a public endpoint or pasted terminal transcript. See Article 3 for topology. A key change does not replace restrictions on database, host, or orchestration access.

What active-data-key rotation actually does

The captured rotation documentation describes a two-layer model: the stable instance master key protects database-held data keys; the active data key encrypts credential data. Rotation activates a new data key for new writes. Older records remain readable, and n8n re-encrypts an older record when it is next updated. Rotation therefore does not instantly rewrite every untouched credential record.

Keep four events distinct in acceptance notes: a new key becomes active; a new or updated n8n credential is stored with it; older records are lazily re-encrypted as updated; and a third-party issuer invalidates an old token. Passing one does not prove the others. The documentation captured 2026-11-06 says rotation is available in self-hosted editions, enabled by default from 3.0 and opt-in on earlier 2.x, with instance-owner control. These dated statements require eligibility and feature-state checks against the selected build.

Before enabling or rotating, take the database backup explicitly required by the docs, preserve relevant .n8n state and configuration artifacts, and test a compatible restore path. Keep the master key unchanged and consistent. Use an authorized instance owner. A successful rotation indicator means the feature accepted the operation; it does not certify that every old record was rewritten or every issuer credential revoked.

Inventory each credential class separately

Use this register as a working worksheet. “Window” means behavior the issuer or selected component documents; “unknown” means resolve it or schedule a maintenance window. Assign an owner per row and test without printing values.

Complete the register before scheduling: owner, issuer, consumer list, current version, storage reference, last rotation, overlap/revocation evidence, backup/escrow reference, test workflow and rollback gate. Unknown consumers or owners remain unresolved rather than guessed.

Protect secret storage and distribution

Keep the real .env outside version control and logs; example files should contain empty values. Do not paste rendered Compose output, environment dumps, screenshots, terminal history, or support bundles containing secrets into tickets. Use a controlled distribution mechanism whose permissions, audit, backup and recovery you understand. A third-party secret manager is not automatically included in an image or plan.

For each secret path, record configuration source and readers, including main, worker, webhook processor, runner, proxy, backup process and deployment automation. Verify file ownership and permissions against the selected image’s actual UID/GID and mount behavior; do not copy a generic numeric owner. Inspect configuration metadata and redacted service status, never environment values or decrypted credentials. Check whether snapshots, replicas, shell history, CI logs, support exports and administrator sessions create additional copies. Transfer only to named recipients; confirm receipt through a separate channel and retire temporary material under policy. Keep recovery authority distinct from routine workflow editing where practical.

For a selected Assistant sandbox, inspect the actual manifest and overrides before claiming .env is excluded: captured prose and manifest evidence conflict. Certificate/key distribution remains open until deployed files and consumers are examined. Give a sandbox only necessary values; it has a separate trust boundary from n8n credentials. See Article 5 for Compose ownership.

Encryption at rest does not determine who may edit workflows or access an administrator session. If one unintended principal can read database, master key, backups and runtime environment, the encryption boundary may not protect against that principal. Review the system’s complete access path.

Reduce workflow and runner access to secrets

A workflow that can use a credential may send data to an external destination. A workflow author or untrusted node may reach beyond the credential’s intended business purpose. Limit editor access, inventory credential sharing, and test the exact permissions your edition and deployment provide.

Captured task-runner guidance recommends external mode for production and sensitive instances; internal mode shares the n8n process user and is not recommended for production. External sidecars must match the documented n8n version; queue deployments need required runner placement for workers. The hardening guide discusses environment exposure through process inspection and runner restrictions. Verify actual topology, token distribution, and allowed environment; never expose the broker publicly.

SSRF protection is an application-layer defense for workflow-controlled requests and complements firewall/network isolation. The captured guide describes blocked ranges and allowlists; an allowlist can intentionally make destinations reachable, so permit only hostnames and ranges under your control. Check the selected release and retain network-level boundaries.

Captured node guidance identifies NODES_EXCLUDE for blocking selected node types, including Execute Command and local-file examples. Verify exact defaults and behavior on the chosen release. Captured 3.0 material says unverified community nodes are disabled by default and existing ones stop loading; N8N_COMMUNITY_PACKAGES_ENABLED=false disables both verified and unverified packages. Package trust is separate from encryption. No one control is a security guarantee.

This is a threat-review prompt, not a risk ranking. Pair it with Article 8 when a packaged image changes default ownership.

Runbook — prepare and perform data-key rotation

This gated procedure is for a self-hosted operator. It uses read-only Bash discovery and a human-confirmed transition because controls and compatibility depend on the selected release. Do not paste values into the worksheet or run commands copied from another version.

Preconditions and read-only discovery

1. Name instance owner, operator, recovery approver and on-call contact. Record UTC window, impact, selected n8n tag and digest, database version, edition, main/worker/webhook services and every writer that must remain compatible.
2. Identify the actual deployment host and Compose project through approved operator records. Confirm environment before any change; do not guess a directory.
3. Verify all components reference the same protected master-key version without printing it. Inspect configuration source and access metadata, not process environments. Confirm authorized recovery owner can reach independent escrow.
4. Read rotation guidance, release notes, migration report and channel-label notice for the exact build. Confirm eligibility, state, supported control, read compatibility and disable threshold. Resolve captured 3.0/channel-label conflict.
5. Take a database backup and verify completion and independent copy. Map .n8n, configuration, external storage, custom/community nodes and other artifacts with Articles 4 and 10. Confirm matching master key escrow and authorized access.
6. Rehearse in isolated staging. Test decryption and a harmless integration without external side effects. Record older versions that cannot read new-format data and prohibit them as fallback after the first new-format write.

#!/usr/bin/env bash
# Read-only host inventory; confirm this is the intended host first.
set -euo pipefail
umask 077
printf 'Host: '; hostname
printf 'UTC: '; date -u +%Y-%m-%dT%H:%M:%SZ
printf 'Operator: '; id -un
printf 'Docker: '; docker --version
printf 'Compose: '; docker compose version
printf '\nRunning containers (names/images/status only):\n'
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
printf '\nCompose projects (names/config paths only):\n'
docker compose ls --format json | jq -r '.[] | [.Name, .ConfigFiles] | @tsv'
printf '\nSTOP: map services and secret sources from approved records.\n'
printf 'Do not run inspect, render config, dump env, or print .env values.\n'

This reads host/container metadata; it does not prove backup, key match, readiness or workflow health. If the tools are unavailable, use the approved read-only inventory method and record it; do not install tools on production for this example.

Controlled change, acceptance and stop branches

After preconditions are signed, use only the selected release’s verified owner control. Captured docs describe Settings → Data Encryption Keys and for 2.x N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true on all instances; an API control is also documented. Recheck labels and controls against the exact build. Do not improvise an endpoint call. Synchronize configuration and follow the reviewed rollout sequence.

1. Record operator, UTC, build, feature state, backup and escrow references, component list and approval. Hold workflow activity only as the rehearsed plan requires; a restart does not drain queue work.
2. Apply reviewed enable/rotation action. Observe supported success metadata without requesting key material. If mismatch, decryption failure, missing authority or backup discrepancy appears, stop and hold new changes.
3. Restart only as the release procedure requires. Verify same master-key reference and compatible versions. Never regenerate the master as troubleshooting.
4. Create/update a harmless test credential using a test issuer account. Verify after approved restart and through representative worker/webhook path. Do not export plaintext. Untouched old records may use a prior data key.
5. Check a representative existing credential/workflow under approved production acceptance. Review redacted logs and audit for failures or exposure. Record tests and unresolved owners.
6. Resume normal intake only after operator and recovery approver accept results and queue/external side effects are reconciled.

Stop and hold: missing owner authority; component key mismatch; no verified database backup; inaccessible escrow; unresolved release/channel uncertainty; older runtime needed for fallback; decryption failure; plaintext exposure. Preserve evidence securely. Do not loop restarts, disable blindly or delete data.

Rollback gate: before new-format writes, restore or redeploy only through a rehearsed compatible app/database/key set. After new-format writes, an older runtime cannot read that format per captured docs; no reverse converter is documented. The stated fallback is restoring the appropriate pre-change backup with matching artifacts and master key, then following Article 10’s isolated acceptance. Automatic rollback is not promised.

Downgrade and disable boundaries are recovery boundaries

When the feature writes sensitive data in the new format with a key identifier, older n8n versions cannot read it. Captured documentation describes no automated conversion to legacy format. A restart or tag change is not rollback. For an incompatible old runtime, the documented recovery route is restoring the appropriate database backup with matching master key and application artifacts.

Captured docs say disabling is safe only from n8n 2.40.3 onward; earlier versions can make newly written data inaccessible if rotation is turned off. This is a version gate, not proof every later build reads every future format. Check exact release notes and migration guidance. Keep the rollback matrix explicit:

Data-key rotation does not rotate the stable master key or revoke third-party tokens. No automated master-key replacement procedure is asserted. Coordinate backup timing with Article 10; RPO/RTO are measured objectives, not feature promises.

Runbook — third-party credential rotation and revocation

Use one run per issuer credential. Plaintext stays out of this document; issuer overlap is a precondition, not an assumption.

1. Select and scope. Record owner, issuer, purpose, scopes, workflows/users, callback or endpoint registration, encrypted n8n record reference, master-key holders, last rotation, exposure and all known consumers. Identify API key, OAuth secret, refresh token, model/search key or other class.
2. Read issuer behavior. Confirm current issuer documentation for overlap, refresh-token/client-secret relationship, callback, revocation effect and old authorization lifetime. If unknown, choose a maintenance window and safe pause; do not infer zero downtime.
3. Prepare protected change. Obtain replacement through approved issuer channel and load directly through authorized n8n credential update. Do not put it in runbook, shell arguments, chat, screenshots or decrypted export. Check authorized users/workflows.
4. Verify before revoke. Run a harmless scoped request from a representative workflow and relevant worker/webhook path. Confirm scope and callback. Check other consumers separately; one passing test does not prove all migrated.
5. Revoke at issuer. When issuer guidance and acceptance permit, revoke/expire old value at source. Record actual response and timestamp. Test rejection only with safe nonproduction client; do not expose production token to prove revocation.
6. Close copies and assign remnants. Review stores, deployment configuration, backups and approved audit sources. Preserve required recovery copies under policy; assign retained copies and expiry. Secure and dispose of any temporary plaintext evidence under incident and retention rules.

Acceptance card: new scope works for each expected consumer; old credential is revoked or remaining validity documented; issuer event recorded; callback matches; n8n master/data-key health checked separately; stored copies have owners; remnants assigned. For exposure, restrict access, preserve approved audit evidence, pause workflows safely, revoke at issuer, rotate other actually exposed DB/Redis/runner/TLS/registry secrets and review workflow editors. One rotation cannot erase every copy.

Backup, escrow and edition procurement

Record the recovery set: database or supported application backup, relevant .n8n files, stable master-key escrow reference, selected app and data-key format compatibility, configuration without secrets in version control, custom/community node dependencies, and external storage/service paths actually used. Article 4 covers database copy boundaries; Article 10 owns restore acceptance.

Do not combine database and master key in a broadly readable archive. Separate access boundaries while retaining an authorized restore path. After restore, assess whether issuer credentials need reauthorization; restored copies may include credentials later revoked.

The captured rotation page says data-key rotation is available in self-hosted editions. This does not make external secrets, Git/environments, SSO, projects or sharing universally available in Community. Confirm current edition matrix and license. Unavailable or unverified capability and price remain unresolved, not $0. See the cost walkthrough and cost tool; do not assume vault, retention or support is included.

For provider selection, ask for evidence about console/API roles, backup encryption/access/retention/restore, incident audit access, and private DB/Redis/runner networks. Verify provider facts at Providers; do not infer escrow or app recovery from a generic VPS listing.

Recovery and problem-handling hand-off

Use the symptom to identify the boundary, inspect redacted metadata and choose a bounded branch. Never put secret values in support requests.

Problem-handling prompt. If a workflow stops after a secret change, capture workflow identity, time, redacted error class, component, selected build and last successful issuer audit event. Ask which class changed, which readers were updated and what compatible recovery boundary applies. This makes feedback actionable without implying incident frequency or vendor quality.

Before routine operations resume, assign the register, confirm independent escrow and recovery owner, check plaintext/log copies, document issuer revocation windows or maintenance choice, and retain compatible rollback artifacts. Keep uncertain capability, cost and provider evidence open. See Methodology for evidence treatment.

Sources and updates

Source capture checked 2026-11-06. These claims describe dated captures; verify selected-release docs before operational changes.

• n8n: Rotate encryption keys — layered keys, controls, backup warning, disable threshold and downgrade limit.
• n8n: Set a custom encryption key — generated key and master-key configuration.
• n8n: Queue mode — shared key for main and workers.
• n8n: Task runners and Harden task runners — runner boundary and environment risks.
• n8n: SSRF protection — outbound controls and network-defense caveat.
• n8n: Block specific nodes, Community node risks, Nodes environment variables — node and package boundaries.
• n8n 3.0 breaking changes and Release notes — selected-build migration and channel-label checks.

Reviewed against local captured sources on 2026-11-06. No live deployment, rotation, restore drill, API call, vendor verification or security test was performed.