Help us improve
Share bugs, ideas, or general feedback.
From n8n-skills
Guides secure credential and secret management in n8n workflows, covering API keys, OAuth, bearer tokens, and native credential types.
npx claudepluginhub n8n-io/skills --plugin n8n-skillsHow this skill is triggered — by the user, by Claude, or both
Slash command
/n8n-skills:n8n-credentials-and-securityThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
1. **Secrets via the credential system, never in text fields or SDK code.** API keys, bearer tokens, OAuth secrets, passwords: all go through `newCredential()` or the node's `credentials` parameter. A Set node hardcoding a token and read via `{{$json.token}}` is a text field with extra steps.
Builds, tests, and deploys n8n workflows via REST API with incremental node testing. Activates for automation creation, workflow debugging, nodes, expressions, credentials, and JS/Python Code nodes.
Configures any n8n node (HTTP, webhooks, database, Slack, AI, triggers) with operation-first parameter shapes and validation. Activates on node-builder calls and parameter configuration.
Creates, edits n8n workflows as TypeScript files with node docs access and n8nac CLI for workspace init, preventing param errors.
Share bugs, ideas, or general feedback.
newCredential() or the node's credentials parameter. A Set node hardcoding a token and read via {{$json.token}} is a text field with extra steps.newCredential('Label') is cosmetic and does NOT bind to a specific stored credential. When the workflow opens, n8n auto-assigns the most recently edited credential of that type to every node, which silently picks the wrong one if the user has more than one (e.g., two Gmail accounts, prod + staging API keys). After building, always tell the user: "Open every node that uses a credential and confirm the right one is selected from the dropdown." Pick a sensible label ('Gmail', 'OpenRouter', 'Acme API') and move on.httpCustomAuth credential type. See references/CUSTOM_CREDENTIALS.md.In n8n, credentials are first-class objects:
A node that needs auth has a credentials parameter pointing to a credential ID + type. Secret values never appear in workflow JSON. Exporting a workflow leaks the reference, not the secret.
For the full model (SDK resolution, rotation, project scoping), see references/CREDENTIAL_SYSTEM.md.
Need to call an external service?
├── Native credential exists (Slack, Gmail, OpenAI, Postgres, ...)?
│ └── Use the native node + its credential type. Done.
│
├── Service is "standard-shaped" (REST + Bearer/Basic/OAuth)?
│ ├── Configure HTTP Request with one of the built-in auth types:
│ │ - Generic OAuth2
│ │ - Header Auth
| | - Bearer Auth (same as header auth but with only field being for actual token)
│ │ - Basic Auth
│ │ - Custom Auth
│ └── See references/HTTP_REQUEST_WITH_AUTH.md
│
└── Service needs multiple static headers, or headers plus query params?
└── Use the httpCustomAuth credential type.
See references/CUSTOM_CREDENTIALS.md
This happens. The user types something like:
"Set up a workflow to call Acme API with bearer
sk-abc123def456"
What to do:
{{$json.token}} is a text field with extra steps.Bearer Auth for bearer tokens, Header Auth for other custom auth headers). When you open it, click the credential dropdown and choose 'Create new credential', and n8n will prompt you for the token there." The credential field on the node will either be empty (no credential of that type exists yet) or auto-filled with the user's most recently edited one of that type (see non-negotiable #2).n8n-extending-mcp for wrapping n8n's credential APIs. The user must provide the secret value, and you should not be the persistent home for it.Common case: the user wants a service n8n has no node for. Use HTTP Request with appropriate auth.
references/FINDING_API_DOCS.md: discovering auth scheme, base URL, common shapes.references/HTTP_REQUEST_WITH_AUTH.md: wiring HTTP Request to a credential.references/CUSTOM_CREDENTIALS.md: when built-in auth types don't fit.| File | Read when |
|---|---|
references/CREDENTIAL_SYSTEM.md | You need to understand how credentials are stored, referenced, scoped, or rotated |
references/CUSTOM_CREDENTIALS.md | Multi-header / header-plus-query auth in one credential, or per-request signing patterns (HMAC, JWT, webhook validation) |
references/HTTP_REQUEST_WITH_AUTH.md | Configuring HTTP Request with auth: Bearer, Basic, OAuth, Header Auth |
references/FINDING_API_DOCS.md | The user mentioned a service you don't have node-level knowledge of |
| Anti-pattern | What goes wrong | Fix |
|---|---|---|
Pasting sk-... into HTTP Request's Authorization header value field | Token in plain text in the workflow JSON, leaks on export, copy, screenshot | Use a credential: Bearer Auth for bearer tokens, Header Auth for other custom auth schemes |
| Storing token in a Set node and referencing via expression | Same problem, value lives in workflow JSON | Same fix: credential, not a Set node |
Storing a secret in $vars.X and reading it as the auth value | Not encrypted at rest, leaks in exports, no rotation | Use the right credential type (httpBearerAuth, httpHeaderAuth, httpCustomAuth, or the native one). For inbound webhook auth, use the trigger's authentication field, not an IF on $vars.token |
Reaching for $env.X to read a secret during custom auth setup | Doesn't work, throws at runtime | Use a credential of the appropriate type |
| Using HTTP Request when a native node exists | Loses auto-refresh on OAuth, loses native error handling, more code | Use the native node |
Hardcoding credentials in SDK code (new HttpRequest({ headers: { Authorization: 'Bearer xxx' } })) | Same leak surface | Use newCredential() in SDK code |
| Asking the user to create a credential without naming the credential type | User picks the wrong type, auth fails confusingly | Always specify: "create a credential of type <exact type name>" |