n8n

n8n Credentials Management: Securing API Keys and Tokens

Ira Menon · Jun 9, 2026 · 15 min read

Why credentials management quietly decides whether your automation is production-ready

Most n8n tutorials start with a trigger node and end with a success message. Nobody shows you the moment three weeks later when a teammate accidentally pastes a live Stripe secret key into a "Set" node because it was faster than opening the credentials panel, or when a workflow gets exported and shared in a Slack channel with an OAuth token sitting in plain text inside the JSON. Credentials are the part of n8n that looks boring until the day it isn't.

If you have been building workflows for a while, you already know that n8n's credential system exists as a separate entity from your nodes for a reason. It is not just a convenience feature that autocompletes your API key into an HTTP Request node. It is the boundary between "workflow that works on my laptop" and "workflow that a security review will actually approve." This article walks through how n8n stores credentials, the practical patterns for keeping keys and tokens safe across environments, and the mistakes that show up over and over again in real automation stacks. If you are building agentic workflows that call multiple external APIs, this is one of the areas where getting the fundamentals right early saves you from a very unpleasant incident report later.

How n8n actually stores your credentials under the hood

n8n separates credentials from workflow definitions at the data model level. When you create a credential — say, an API key for OpenAI or an OAuth2 connection to Google Sheets — it is saved as its own database record, encrypted, and referenced by workflows through an ID rather than being embedded directly in the node parameters.

A few things worth understanding about this architecture:

Encryption at rest. n8n encrypts credential data using an encryption key that is generated on first startup and stored in the ~/.n8n/config file (or wherever your N8N_USER_FOLDER points). This key is what makes the encrypted blobs in the database unreadable without it.
The encryption key is the actual secret. This is the part people miss. Your database backup, if leaked, is only as dangerous as whether the attacker also has your encryption key. If you self-host, this key deserves the same treatment as a root password — not a value you paste into a Notion doc or leave in a shell history file.
Credentials are referenced, not duplicated. A single "Postgres - Production DB" credential can be used across dozens of workflows. This is good for rotation (change it once, every workflow picks up the new value) but it also means one over-permissioned credential can become a blast radius problem if it's misused in a workflow you didn't review carefully.
Node-level masking. In the editor UI, credential values are masked by default and n8n makes a deliberate effort to avoid printing raw secret values into execution logs. This matters because execution data is often retained for debugging, and you do not want your Stripe secret key sitting in plaintext inside an execution log that ten people on your team can read.

Understanding this model changes how you think about workflows. A workflow JSON export does not contain your actual API key — it contains a reference to a credential ID that only resolves inside your specific n8n instance. That is a deliberate security boundary, and it is also why importing someone else's workflow template never "just works" for the credentialed nodes; you always have to reconnect your own credentials.

Setting the encryption key correctly from day one

If you are self-hosting n8n — whether on a VPS, inside Docker, or on Kubernetes — the single most important early decision is how you manage the encryption key.

By default, n8n auto-generates this key on first boot and stores it locally. That is fine for a solo experiment, but it creates a real problem the moment you:

Restart a container without a persistent volume (you lose the key, and every existing credential becomes permanently undecryptable)
Scale to multiple n8n instances (each instance needs the *same* key, or credentials created on one node cannot be read on another)
Migrate to a new server (forgetting to carry the key over bricks your entire credential store)

The fix is to set the key explicitly using the N8N_ENCRYPTION_KEY environment variable, generated once and stored in your infrastructure's secret manager rather than left to auto-generation.

# Generate a strong random key once
openssl rand -hex 32

# Then set it as an environment variable wherever n8n runs
export N8N_ENCRYPTION_KEY="your-generated-key-here"

In a Docker Compose setup this looks like:

services:
  n8n:
    image: n8nio/n8n
    environment:
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
    env_file:
      - .env
    volumes:
      - n8n_data:/home/node/.n8n
volumes:
  n8n_data:

Keep N8N_ENCRYPTION_KEY out of your docker-compose.yml itself and out of version control. Pull it from your secret manager (AWS Secrets Manager, Doppler, HashiCorp Vault, or even a properly permissioned .env file that is gitignored and never committed) at deploy time. Losing this key is not a "reset your password" situation — it means every stored credential becomes garbage, and you will be reconnecting every single integration in every workflow by hand.

Choosing the right credential type for the job

n8n supports several credential types, and picking the right one is itself a security decision, not just a matter of convenience.

API Key credentials are the simplest — a static string sent as a header or query parameter. They are easy to set up but also the easiest to leak, since there is no expiry and no automatic rotation. Treat every API key credential as something that needs a manual rotation schedule.
OAuth2 credentials are generally the safer default when a service supports them. Tokens are short-lived, refresh automatically, and a compromised access token has a limited window of usefulness. The tradeoff is more setup complexity — you need to register an OAuth app with the provider and configure redirect URLs correctly.
Header Auth / Custom Auth credentials give you flexibility for APIs that don't fit the standard patterns, letting you define exactly which headers or query parameters carry the secret. Useful for internal APIs or less common vendors, but it puts more responsibility on you to get the scoping right.
Generic credentials for databases and SSH (Postgres, MySQL, SSH, etc.) carry their own risk profile since a leaked database credential can expose far more than a single API's worth of data. These deserve read-only database users wherever the workflow doesn't need write access.

A pattern worth adopting: whenever a service offers both a long-lived API key and OAuth2, default to OAuth2 unless you have a specific reason not to (for example, a background job with no user present to complete an OAuth consent flow). The self-refreshing nature of OAuth tokens means a leaked token is a smaller, shorter-lived problem than a leaked static API key that works until someone manually revokes it.

Scoping credentials with the principle of least privilege

It is tempting to create one API key with full account permissions and reuse it everywhere because it's simpler. Resist this. Nearly every serious API provider — Stripe, AWS, Google Cloud, Notion, Airtable — lets you scope a key or token down to only the permissions a specific workflow needs.

Concrete practices that pay off:

Create separate keys per workflow purpose, not per person. A workflow that only reads Airtable records should use a read-only API key, even if a full read-write key would technically work. If that credential leaks, the damage is capped at "someone can read data" rather than "someone can delete your base."
Use scoped service accounts for cloud APIs. For Google Cloud or AWS integrations, create a dedicated service account with IAM policies limited to the exact resources the workflow touches, rather than reusing your personal admin credentials inside n8n.
Separate credentials by environment. Your staging workflow and production workflow should never point at the same API key. This sounds obvious until you're debugging a workflow at 11pm and it's faster to just point staging at the prod key "for now." That "for now" is how staging bugs turn into production incidents.
Name credentials descriptively. "Stripe - Read-only - Refund Automation" tells the next person what this key can do and why it exists. "Stripe 2" tells them nothing, and six months later nobody wants to touch it for fear of breaking something.

Least privilege is not a one-time setup task — it's a discipline you apply every time you wire up a new node. The extra two minutes it takes to generate a scoped key instead of reusing the master key is cheap insurance against a much more expensive cleanup later.

It also pays off in ways that aren't purely about security. A tightly scoped credential is self-documenting — anyone reviewing the workflow can look at the credential name and permission level and immediately understand what the automation is allowed to touch, without having to trace through every node to figure out the actual blast radius. When an incident does happen (and eventually one will, at some scale), the first question is always "what could this credential have accessed," and a scoped, well-named key answers that in seconds instead of requiring you to reconstruct the answer from provider logs under pressure.

Managing credentials across teams with n8n's access controls

If you're running n8n in a team setting (which is standard once you move past personal automation and into an actual company workflow), credential sharing and ownership become a real governance question.

n8n's project and role-based access system (available in its team/enterprise tiers, and increasingly in the community edition's project structure) lets you:

Assign credentials to specific projects rather than making every credential globally visible to every user in the instance.
Control who can use a credential in a workflow versus who can view or edit its actual secret values. A workflow builder should often be able to *select* a credential from a dropdown without ever seeing the underlying key.
Separate credential owners from workflow owners. The person who created a Salesforce OAuth connection isn't necessarily the person who should be editing every workflow that touches Salesforce.

Practical team habits that reduce risk:

Designate one or two people as "credential owners" for each major integration (payments, CRM, email, database) rather than letting anyone create ad hoc keys for the same service.
Require a lightweight review before a new credential type gets added to production — even just a Slack message asking "does this need write access or just read?"
Audit credential lists quarterly. n8n instances accumulate stale credentials from experiments and abandoned workflows; each one is a dangling risk if it's still valid but nobody remembers what it does.
When someone leaves the team, rotate every credential they had access to, not just their n8n login. Access to the n8n instance often implies access to whatever credentials are stored inside it.

Rotating keys and tokens without breaking production workflows

Rotation is the part of credentials management everyone agrees is important and almost nobody does consistently, because it feels risky — what if the new key doesn't work and you've just broken five production workflows?

A safer rotation pattern:

Generate the new key or token from the provider without revoking the old one yet. Most providers (Stripe, GitHub, AWS) let multiple valid keys exist simultaneously for exactly this purpose.
Update the credential in n8n using the new value. Because credentials are referenced by ID across workflows, you only update it in one place and every workflow using that credential picks up the new value immediately.
Run a manual test execution on at least one workflow using that credential before considering the rotation complete. Use n8n's manual execution feature to trigger a real call against the new key.
Watch the execution log for the next few scheduled runs to confirm nothing silently failed. n8n's execution history is your quickest way to catch an authentication failure before it becomes a customer-facing incident.
Revoke the old key at the provider only after you've confirmed the new one is working across all dependent workflows.

For credentials tied to compliance requirements (payment processing, health data, anything under SOC 2 scope), build rotation into a recurring calendar reminder rather than relying on memory. A quarterly rotation cadence for high-sensitivity API keys is a reasonable default if the provider doesn't force automatic expiry already.

Rotation checklist (copy into your runbook):
1. Generate new credential at provider (keep old one active)
2. Update credential value inside n8n UI
3. Manually execute one workflow using this credential
4. Check execution log for auth errors
5. Monitor next 2-3 scheduled runs
6. Revoke old credential at provider
7. Document rotation date for compliance audit trail

Common credential mistakes that show up in real n8n instances

A few patterns come up repeatedly when reviewing n8n setups that have been running for a while:

Secrets pasted into Set or Function nodes instead of stored as credentials. This usually happens when someone needs a quick one-off header value and it's faster to hardcode it than configure a proper credential. It works, until that workflow gets exported, shared, or duplicated, and now the secret travels with it in plain text.
Using the same credential across dev, staging, and production because managing three separate keys felt like overhead. This is how a bug in a test workflow ends up sending real emails to real customers or hitting a production payment API.
Never rotating credentials after an employee offboarding. If someone had access to the n8n instance, assume they saw or could see every credential in it, and rotate accordingly.
Storing webhook signing secrets loosely. Incoming webhook triggers often need to validate a signature (Stripe, GitHub, and similar services all sign their payloads). That signing secret deserves the same credential-store treatment as an outbound API key — not a hardcoded string inside a Function node that verifies the signature.
Ignoring credential-level test/connection checks. Most n8n credential types include a "test" button that verifies the connection actually works. Skipping this and only finding out a credential is broken when a scheduled workflow silently fails at 3am is an avoidable failure mode.
Overusing global environment variables for secrets that should be scoped credentials. n8n does support environment variables via expressions, but stuffing every secret into .env variables instead of the credentials system loses you the encryption, access control, and per-workflow scoping that the credentials system is built for.

Most of these mistakes are not exotic — they are the same shortcuts every team takes under deadline pressure. The fix is rarely a new tool; it's a habit of routing every secret through the credentials panel by default, without exception, even when the "just paste it in a Set node" path feels faster in the moment.

There's also a subtler version of this problem worth watching for: credentials that are technically stored correctly but are still over-exposed through workflow design. If a workflow logs the full response body of an authenticated API call, and that response happens to echo back a token or a masked-but-reconstructable identifier, you've effectively leaked the credential's context even though the credential itself was stored properly. Treat what a workflow logs and returns with the same scrutiny you apply to where the secret itself lives — encryption at rest doesn't help if the workflow prints the sensitive value into an execution log anyway.

Building this into how you design workflows from the start

The best time to think about credentials management is before you build the workflow, not after a review flags it. When you're designing a new automation — especially one that's part of a larger agentic system calling multiple APIs in sequence — a few questions are worth asking upfront:

Does this workflow need write access, or would read-only cover it?
Should this run under a dedicated service account rather than a personal API key?
If this credential leaked tomorrow, what's the actual blast radius, and is that acceptable?
Who else needs to use this credential, and should they see the raw value or just be able to select it from a dropdown?
Is there a webhook signature or callback secret in this workflow that also needs to be stored securely, not just the outbound API keys?

Treating these as design questions rather than afterthought fixes is what separates automation that survives a security review from automation that gets flagged and sent back for rework. It is a small mental shift — credentials as a first-class design concern rather than plumbing you configure at the end — but it compounds. Every workflow you build this way is one less thing you have to go back and fix later, and one less item on the list when an actual audit happens.

If you're building serious automation systems with n8n — particularly ones that chain AI agents together with external tools, APIs, and data sources — credential hygiene isn't a side topic, it's part of the core architecture. Our n8n AI Agent Tutorial course at teachyou.ai goes deep into building production-grade agentic workflows in n8n, including how to structure credentials, environments, and access controls so what you build doesn't just work in a demo — it holds up when it's actually running your business.