Security and Credentials Management
Managing API keys, secrets, OAuth and sensitive data. Webhook security, rate limiting and monitoring.
In this chapter
n8n is powerful but misconfigured it opens serious security holes: open webhook URLs become attack surfaces, a leaked API key gives access to your Slack workspace, an OAuth token that didn't refresh leaves the system silently broken. In this chapter you'll learn everything required to stay safe in production: how credentials are encrypted, OAuth2 token flow and refresh, HMAC webhook signature verification, rate limiting and abuse protection, PII masking, audit logs and access control.
Topics
- Credentials store: encryption at rest
- OAuth2 flow and token refresh
- Webhook secret / HMAC verification
- Rate limiting and abuse protection
- Masking sensitive data and PII
- Audit logs and access control
Credentials store: how encryption at rest works
n8n doesn't store credentials in plain text (API keys, passwords, tokens, OAuth client secrets). All credentials are AES-256-CBC encrypted and written to the database encrypted. The key is the N8N_ENCRYPTION_KEY env variable. Therefore: (1) Set the ENCRYPTION_KEY MANUALLY in production (`openssl rand -hex 32`) — don't rely on n8n auto-generating. (2) Back up the key in at least 3 places: password manager + offline written + backup server. (3) Lose the key and all credentials are unrecoverable — you must re-enter every credential. (4) A Postgres backup without the ENCRYPTION_KEY is useless — keep both, but NOT in the same place.
OAuth2: client_id, client_secret and refresh
You talk to Google, Microsoft, Slack, HubSpot via OAuth2. Flow: (1) Create an OAuth app at the provider (Google Cloud Console / Slack App Directory etc.). (2) Use the URL shown in n8n's credential as the Redirect URI (most providers reject non-HTTPS). (3) Paste Client ID + Client Secret into the n8n credentials → click 'Connect my account' and approve. n8n now stores access + refresh tokens. The access token typically expires in 1 hour; n8n auto-refreshes with the refresh token. Pitfall: refresh tokens may be limited or expire after 6 months of inactivity — add a monthly 'health check' workflow per critical OAuth connection (hit a no-op API and alert on failure).
Webhook security: unsigned webhook is an open door
Your n8n webhook URL is on the public internet. With no verification an attacker can guess the URL or find it in logs, send forged requests, send emails on your behalf, write to your DB, or rack up an OpenAI bill. Minimum 4 layers: (1) Header secret: enable 'Authentication: Header Auth' on the webhook, set a name + value; missing header = 401. (2) Path token: put an unguessable UUID in the URL itself (`/webhook/9f2e...8a1c`). (3) HMAC signature: for critical webhooks (Shopify, Stripe, GitHub) — next section. (4) IP whitelist: a reverse proxy rule (Cloudflare, Nginx allow/deny) that allows only known sender IPs. Apply at least 2 layers in production.
HMAC signature verification: Stripe, Shopify, GitHub pattern
Professional APIs (Stripe, Shopify, GitHub, Twilio) HMAC-SHA256 their webhook payload with a shared secret and put the hash in a header like 'X-Hub-Signature-256' / 'Stripe-Signature.' You must hash the same payload with the same secret and compare; mismatch means forged. n8n recipe: enable 'Raw Body' on the Webhook node (mandatory — JSON parsing changes bytes, hash won't match) → in a Code node `crypto.createHmac('sha256', secret).update($input.first().binary.data.data).digest('hex')` → IF compare with the incoming header → on mismatch Respond 401, otherwise continue. Use crypto.timingSafeEqual for constant-time comparison (`==` is vulnerable to timing attacks).
Rate limiting and abuse protection
If you have an open AI workflow (e.g. a customer chatbot) and no rate limit, a bad actor can fire 100 requests/sec and turn your OpenAI bill into $1,000 overnight. Layers: (1) Reverse proxy: Cloudflare/Nginx rate limit (30 req/min per IP). (2) Workflow level: at the first node track 'requests for this IP+endpoint in the last minute' in Redis/Postgres; over the threshold return 429. (3) Token budget: per-user daily token spend in the DB, soft-block when exceeded. (4) reCAPTCHA: on user-facing flows that need a human. (5) Kill switch: an IF gate driven by a single env (`AI_ENABLED=false`) that lets you stop all AI workflows in 5 seconds when you see abnormal spend.
PII masking and data minimisation
GDPR (and Turkey's KVKK) ask for data minimisation: don't keep personal data you don't need, anonymise what you do. Practical n8n: (1) Never log raw PII — use Set to mask emails ('a***@gmail.com'), phones (last 4 digits, `***1234`), national IDs (hash only). (2) When sending names/IDs to the LLM, use anonymous placeholders ('{user_name_1}') and substitute back in the user-facing reply — the real name doesn't sit in model logs. (3) Encrypt sensitive columns in Postgres with 'pgcrypto.' (4) Retention: auto-delete execution logs after 30 days (EXECUTIONS_DATA_MAX_AGE), backups after 90. (5) Document the 'right to be forgotten' flow: which workflow + table + S3 path gets purged when a user requests deletion.
Audit log and access control: who, what, when?
In production n8n you must know three things: who changed which workflow, who used which credential, who manually ran which execution. The Enterprise license has built-in Audit Log; on community you do it yourself: (1) Forward n8n's stdout to Loki/Elasticsearch, parse and store 'user-action' events in a table. (2) Commit workflow JSONs to git daily — git history tells you who changed what. (3) For multi-user: n8n RBAC (Enterprise) or at least one n8n instance per user + reverse proxy basic-auth for separation. (4) Credential access levels: assign 'Owner' / 'Member' correctly — not everyone can access every credential. (5) 2FA: on n8n.cloud yes; on self-host SSO/SAML (Enterprise) — without it a single password unlocks the whole system.
Security checklist: before going to production
Don't ship a workflow that fails any of these 10 items. (1) HTTPS active, cert valid? (2) N8N_ENCRYPTION_KEY set and backed up? (3) All webhooks have Header Auth or HMAC? (4) Webhook URLs use unguessable UUIDs? (5) Rate limit rules (proxy + workflow) defined? (6) PII in logs checked and stripped? (7) EXECUTIONS_DATA_MAX_AGE set (30-90 days)? (8) Monthly health-check workflow for OAuth connections? (9) If the n8n editor URL is public, is it behind basic-auth or a VPN? (10) Was a restore drill done in the last 3 months? Pass this list once during setup; every workflow afterwards is born safe.
This chapter's workflow (n8n editor view)