// Use when handling any auth, API keys, tokens, OAuth, bearer tokens, basic auth, or secret values in n8n workflows. Triggers on "API key", "token", "bearer", "OAuth", "secret", "auth", "credentials", "Authorization header", "x-api-key", or any node configuration that mentions a third-party service.
Use when writing or reviewing n8n SDK code that wires IF, Switch, Merge, error outputs, or any multi-input/multi-output connection. Triggers on .add(), .to(), .input(n), .output(n), .onTrue, .onFalse, .onCase, .onError, useDataOfInput, merge, switch, IF nodes, error branches, fan-out, fan-in, or any review of the workflow's connections object.
Use when starting, designing, organizing, finishing, or shipping an n8n workflow. Covers visual layout (sticky notes), descriptions that capture the *why*, node names, validation, testing, folders/projects, and publishing. Triggers on create_workflow_from_code, update_workflow, validate_workflow, publish_workflow, archive_workflow, "design", "lay out", "organize", "structure", "sticky", "describe this workflow", "ship", "deploy", "publish", "name this workflow", or any folder/project organization request.
Use when working with n8n workflows in any capacity. The always-on protocol for the n8n-skills plugin, loaded by the SessionStart hook every session. Routes to the right skill, summarizes every n8n MCP tool (closing the deferred-description gap), and lists the cross-cutting rules.
Use when building or editing any AI feature in n8n: AI Agents, Text Classifier, Information Extractor, Sentiment Analysis, Summarization Chain, Basic LLM Chain, embeddings, vector stores, single one-shot LLM calls, or AI media generation (image / audio / video) via the native LangChain provider nodes. Triggers on any `@n8n/n8n-nodes-langchain.*` node, "agent", "chat assistant", "LLM with tools", "tool calling", "fromAi", "system prompt", "memory window", "structured output", "outputParser", "function calling", "RAG", "vector store", "embeddings", "classify with AI", "extract fields with LLM", "sentiment analysis", "summarize with LLM", "single LLM call", chat triggers with files, AI image / video / audio generation, or any multi-turn or one-shot LLM behavior.
Use when building anything multi-step, anything that looks repeatable, anything the user mentions reusing, or any workflow with more than ~10 nodes. Triggers on "reuse", "I do this in another workflow", "extract", "modular", "shared logic", "subworkflow", multi-step builds, or any task that mentions logic the user has built before.
Use when the user reaches for a Code node, mentions writing JavaScript or Python in n8n, or any custom logic comes up in workflow design. Triggers on "Code node", "Code", "JavaScript", "Python", "custom logic", "transform data", "$input", "$json transformation", "loop in code", "write a function", or any time the obvious answer seems to be "just put it in code."
| name | n8n-credentials-and-security |
| description | Use when handling any auth, API keys, tokens, OAuth, bearer tokens, basic auth, or secret values in n8n workflows. Triggers on "API key", "token", "bearer", "OAuth", "secret", "auth", "credentials", "Authorization header", "x-api-key", or any node configuration that mentions a third-party service. |
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>" |