Credentials & Authentication
Relevant source files
The following files were used as context for generating this wiki page:
- packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md
- packages/nodes-base/AGENTS.md
- packages/testing/playwright/tests/e2e/credentials/crud.spec.ts
- packages/testing/playwright/tests/e2e/workflows/templates/credentials-setup.spec.ts
- packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json
- packages/nodes-base/TESTING_PROMPT.md
Credentials in n8n are specialized entities used to store sensitive information required to connect to external services and APIs. They abstract authentication logic away from individual nodes, allowing sensitive data like API keys, OAuth2 tokens, and passwords to be managed centrally and securely. Nodes within a workflow reference these credentials to perform authenticated requests without exposing the underlying secrets in the workflow JSON.
The authentication system supports various methods, including Basic Auth, Header Auth, and OAuth2. While nodes can handle simple authentication via parameters for tutorial purposes, n8n enforces a strict best practice of using the built-in credentials system for production workflows to keep secrets safe and out of plain text.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md, packages/frontend/editor-ui/src/features/workflows/templates/utils/samples/tutorial/api_fundamentals.json
Credential Architecture and Implementation
Core Components
Credentials are implemented as distinct classes or files that fulfill the ICredentialType interface. Every package containing community nodes usually includes a credentials folder with individual files for each credential type.
| Component | Description |
|---|---|
name | Internal identifier used by nodes to reference the credential. |
displayName | Human-readable name displayed in the n8n UI. |
properties | An array of fields (e.g., text, password) that a user must fill to configure the credential. |
authenticate | Configuration for how the credential should be applied to requests (e.g., as a header or query parameter). |
test | A method used to verify if the provided credential data is valid by making a test request to the service. |
Sources: packages/nodes-base/AGENTS.md, packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md
Credential Definition Flow
The following diagram illustrates how credentials are defined and registered within an n8n package.
The package.json file in a node package must explicitly list the transpiled JavaScript paths of the credentials in the n8n.credentials key for them to be recognized by the platform.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md:36-54
Authentication Mechanisms
The system supports multiple standard and custom authentication patterns. When a node requires authentication, it can offer multiple "modes" or "auth options" (e.g., choosing between OAuth2 and Service Account for Google services).
Common Authentication Modes
- Header Auth: Passes credentials (like
x-api-key) in the HTTP headers. - Basic Auth: Uses standard username and password encoding.
- OAuth2: A more complex flow involving client IDs, secrets, and redirect URLs.
- Query Auth: Appends authentication tokens as query parameters to the URL.
- JWT Auth: Uses JSON Web Tokens with either shared secrets or PEM public/private keys.
Sources: packages/testing/playwright/tests/e2e/credentials/crud.spec.ts, packages/cli/src/modules/mcp/tests/webhook-utils.test.ts
Node-Credential Interaction
Nodes interact with credentials through specific execution functions. During workflow execution, the getCredentials helper retrieves the decrypted credential data.
Credential Management Operations (CRUD)
The n8n UI provides a dedicated interface for managing the lifecycle of credentials, which is also heavily exercised via E2E testing.
- Creation: Users can create credentials from a global list or directly from the Node Development View (NDV) when configuring a node.
- Renaming/Editing: Existing credentials can be updated or renamed, which reflects across all nodes referencing them.
- Deletion: Credentials can be removed, though this will cause nodes relying on them to show an "empty state" or error.
- Filtering: In multi-project environments, credentials can be filtered by Project ID to ensure users only see relevant accounts.
Sources: packages/testing/playwright/tests/e2e/credentials/crud.spec.ts, packages/testing/playwright/tests/e2e/projects/projects.spec.ts:110-120
Security Best Practices
Untrusted Values
A critical security rule for credential and node development is to never use untrusted values (user inputs) as computed object keys in assignments. This prevents prototype pollution. Developers are instructed to use helpers like setSafeObjectProperty and isSafeObjectProperty from n8n-workflow.
import { setSafeObjectProperty, isSafeObjectProperty } from 'n8n-workflow';
if (isSafeObjectProperty(table) && acc[table] === undefined) {
setSafeObjectProperty(acc, table, {});
}
Sources: packages/nodes-base/AGENTS.md:71-92
Template Setup
When workflows are imported from templates, a "Credential Setup" experience guides users to configure all required credentials before the workflow is created. This ensures the "Kitchen" (Server) and the "Customer" (Client) nodes are correctly linked from the start.
Sources: packages/testing/playwright/tests/e2e/workflows/templates/credentials-setup.spec.ts
Testing Credentials
Unit Testing with Mocks
Developers use vitest-mock-extended to mock the credential retrieval process. The getCredentials function is typically mocked to return a resolved promise containing test tokens or API keys.
// Credentials mocking example
mockExecuteFunctions.getCredentials.mockResolvedValue({
accessToken: 'test-token',
baseUrl: 'https://api.example.com'
});
Sources: packages/nodes-base/TESTING_PROMPT.md:46-51
Workflow Integration Tests
For full workflow tests, NodeTestHarness is used to define a virtual environment where specific credential IDs map to test data objects.
Sources: packages/nodes-base/TESTING_PROMPT.md:144-162
Summary
Credentials and Authentication form the security backbone of n8n. By isolating sensitive information into managed ICredentialType entities, n8n ensures that workflow logic remains portable and secure. The system provides a robust framework for developers to implement standard authentication protocols while providing users with a centralized interface for secret management.