n8n Credentials and Secrets Management

Why n8n credential management matters

An n8n workflow often sits between the systems a business cares about most: email, CRM, billing, databases, analytics, files, chat, and AI providers. A single workflow can read customer records, send messages, update invoices, and call a model with private context. That makes credentials the control plane for the automation, not a setup detail you can forget after launch.

The common failure is not a cinematic breach. It is a copied bearer token in a test node, a workflow export pasted into a ticket, a contractor using the owner account, a backup restored onto a staging host with production credentials, or an old key still active after the workflow owner changed teams. Each one is boring, and boring is exactly why it survives audits.

A good credentials model gives builders enough freedom to ship without letting every workflow become a permanent exception. The goal is not to make n8n painful. The goal is to make the safe path the fastest path: named credentials, scoped accounts, clear ownership, rotation that does not break production, and incident steps that can be followed under pressure.

The production secret model for n8n

Think of n8n secrets in layers. The first layer is the platform secret that protects n8n itself, especially the encryption key used for stored credentials. The second layer is the credential record inside n8n that a workflow node references. The third layer is the upstream account or token at the vendor, such as a Google OAuth app, Slack bot token, OpenAI API key, Postgres user, or payment processor restricted key.

Each layer has a different owner and a different rotation method. Platform secrets belong to infrastructure. n8n credential records belong to workflow owners. Upstream service accounts belong to the system owner. When those roles are blurred, nobody knows whether a key can be rotated, which workflows will fail, or who approved the scope in the first place.

The clean model is explicit: one credential record maps to one business purpose, one owner, and one upstream identity where possible. A workflow named invoice enrichment should not quietly share the same all-powerful CRM token as newsletter tagging. Sharing feels efficient until one workflow needs to be retired, one vendor connection is compromised, or one team asks for proof that a workflow cannot touch records outside its remit.

Where each kind of n8n secret should live

The table below is the policy most teams need before they add more automations. It is deliberately plain because complicated secret diagrams tend to hide accountability instead of improving it.

A copy-paste credential inventory starter

The inventory can live in your private operations repo, ticketing system, or password manager notes. What matters is that it names the owner, purpose, upstream account, and rotation path. Do not put real secret values in this file. One value deserves special care: if N8N_ENCRYPTION_KEY is lost or changed, every stored credential becomes undecryptable, so set it explicitly and back it up. If you never set it, n8n auto-generates one and persists it at ~/.n8n/config on the host, which is fine until a restore lands on a machine that does not have that file.

# n8n production secret checklist, adapt names before use
N8N_ENCRYPTION_KEY=replace-with-32-plus-random-characters
N8N_HOST=automation.example.com
N8N_PROTOCOL=https
N8N_SECURE_COOKIE=true

credential_inventory:
  owner: [email protected]
  business_purpose: invoice enrichment workflow
  n8n_credential_name: crm-invoice-readonly-prod
  upstream_account: crm_n8n_invoice_reader
  allowed_scopes:
    - contacts.read
    - invoices.read
  forbidden_scopes:
    - contacts.delete
    - billing.write
  rotation_cadence: quarterly
  last_rotation: 2026-06-30
  rollback_contact: ops-on-call

Rotation without breaking production

Rotation fails when teams treat it as a single event. In production, rotation is a small migration: create a new upstream credential, add it to n8n, run the workflow in a controlled path, switch the active credential reference if needed, observe executions, then revoke the old key. The dangerous version is deleting the old key first and discovering that three workflows silently depended on it.

For OAuth credentials, the rotation event may mean reauthorizing the app, changing scopes, or creating a new app registration. For API keys, it may mean two active keys during a short overlap. For database users, it may mean creating a new role and password, then proving the query set still works. The runbook should name the vendor-specific method rather than saying rotate key as if all systems behave the same.

A practical cadence is risk-based. Customer data, payment data, production databases, and AI provider keys with high spend limits deserve tighter review. Low-risk internal tools can rotate less often, but they still need an owner and an exit path. The cadence matters less than whether the first rotation has actually been practiced.

A six-step credential rotation runbook

This runbook is intentionally small enough to execute during maintenance without inventing process on the spot. The important part is the order: prove the replacement works before you remove the old path.

1. Inventory every credential. Export the list of credential names from n8n, then map each one to owner, workflow, upstream service, data class, and last rotation date.
2. Classify risk before editing. Separate low-risk read-only tools from credentials that can move money, expose regulated data, send external messages, or write to production databases.
3. Create the replacement upstream key first. Add a new vendor token or service account with the intended scope while the old key still works, so testing does not begin with an outage.
4. Update the n8n credential record. Change the credential value or create a new named record, then run a controlled test execution that covers the highest-risk branch.
5. Observe real executions. Watch the next scheduled runs, execution logs and monitoring, and vendor audit logs before revoking the old credential.
6. Revoke the old key and write the note. Disable the old upstream secret, record the date, owner, reason, and any workflow changes discovered during the rotation.

Worked example: one CRM token, three workflows

Assume a small company has one CRM API token used by three n8n workflows: lead enrichment, renewal reminders, and invoice lookup. The token belongs to an admin user and can read, write, and delete records. Nothing is broken yet, but the risk is already concentrated. If the token leaks, the blast radius is the whole CRM. If the admin leaves, nobody knows what will stop working.

The fix is not to rename the token. Create three upstream service accounts or three scoped API keys if the CRM supports them. Lead enrichment gets contact read and enrichment write. Renewal reminders get account read and message draft permission. Invoice lookup gets invoice read only. Then create three n8n credential records with names that describe the purpose, not the person who created them.

The migration can happen one workflow at a time. Start with the read-only invoice lookup because it has the lowest rollback cost. After a clean run, move renewal reminders, then lead enrichment. Once all three run cleanly, revoke the original admin token. The final state is easier to audit and easier to change because each credential tells you what it is allowed to do.

Common mistakes that create secret sprawl

Access control around credentials

Credential storage is only one side of the risk. The other side is who can use the credential through a workflow. A user may never see the raw API key and still be able to trigger a workflow that spends money, exports customer data, or updates production systems. That is why n8n access should be reviewed by action, not just by whether a person can view secret values. Record those access decisions in your automation governance policy so each review starts from a known baseline.

Start with named users and named owners. Avoid shared admin accounts, especially for contractors and temporary build partners. If a person only needs to edit a sandbox workflow, do not give them production credentials by convenience. If they need production access for a short migration, record the reason and the removal date before the work starts.

The review should include executions, not only settings. Look at who can manually run workflows, who can edit credentials, who can duplicate workflows into another project, and who can export JSON. Those permissions shape the real blast radius. A credential that is encrypted at rest can still be misused if too many people can route work through it.

Backups, exports, and staging restores

The quietest credential leak is often a backup or a staging restore. A team may handle production API keys carefully inside the app, then copy the database to a less protected environment for debugging. Even when credential values are encrypted, the backup can carry credential names, workflow intent, endpoint URLs, account IDs, and enough operational context to make an attacker or careless insider dangerous.

Production backups should have their own access policy and expiry. They should not be downloadable by every developer who can edit a workflow. If a staging restore is needed, decide whether production credentials should be removed, replaced with sandbox credentials, or blocked by network policy before anyone opens the instance. A restored n8n instance that can still call production vendors is not a harmless test environment.

Workflow exports deserve similar treatment. They are useful for version control and review, but they should go to a private repo under version control with the same discipline as infrastructure code. Review diffs for credential references, webhook URLs, internal hostnames, and comments that reveal how the business process works. Secrets management is strongest when the surrounding artifacts are treated as part of the same system.

The simplest acceptance test is whether a new operator can answer three questions in five minutes: what systems can this credential touch, who approved that scope, and how do we revoke it without guessing? If the answer depends on memory, the credential model is not production-ready yet.

What other experts say

Ship a safer n8n credential setup this week

• Set the encryption key explicitly. Define N8N_ENCRYPTION_KEY from the host or secret manager and store a backup copy off the instance so a restore can decrypt existing credentials.
• Export the credential list and assign owners. Map every credential name to one owner, one workflow, one upstream account, and a data class before adding anything new.
• Replace shared admin tokens with scoped accounts. Create one upstream service account per business purpose so a leak or offboarding does not affect every workflow at once.
• Purge secrets from Set nodes and node parameters. Search workflows for inline tokens, move each to a named credential record, and re-test the workflow.
• Lock down exports and backups. Move workflow JSON to a private repo with restricted access, and give production backups their own access policy and expiry.
• Rehearse one rotation end to end. Create a new key, switch the reference, watch real executions, then revoke the old key, and write down the date and owner.
• Review access by action, not just visibility. Confirm who can run, edit, duplicate, or export each workflow, and remove contractor and temporary access on a fixed removal date.

Credential hardening readiness card