Credentials Management & Encryption

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/credentials/validation.ts
• packages/core/src/tests/credentials.test.ts
• packages/cli/test/integration/environments/source-control-export.service.test.ts
• packages/nodes-base/AGENTS.md
• AGENTS.md
• packages/frontend/editor-ui/src/features/credentials/components/CredentialEdit/CredentialConfig.vue

n8n uses a centralized system to manage sensitive authentication data required by nodes to connect to external services. This system ensures that secrets remain encrypted at rest and provides mechanisms for validation, external secret referencing, and secure export.

Encryption Architecture

The core of the security model is the Cipher and EncryptionKeyProxy. n8n encrypts and decrypts data only through cipher.encryptV2() and cipher.decryptV2(), ensuring that the key management module controls which key and output format are used.

Data at Rest

Credential data is stored in the database as an encrypted string. The system uses an instance-specific encryption key to wrap Data Encryption Keys (DEK).

Key Management

The KeyManagerService handles deployment keys. These keys are never deleted to prevent data from becoming unreadable; instead, they are deactivated if necessary.
Sources: AGENTS.md:209-211, packages/core/src/tests/credentials.test.ts:24-28

External Secrets & Vaulting

n8n supports referencing secrets stored in external providers (e.g., HashiCorp Vault, AWS Secrets Manager) using expressions like $secrets.

Validation Flow

When a user saves or updates a credential containing external secret expressions, the system performs two primary checks:

1. Permissions Check: Validates if the user has externalSecret:list scopes for the specific project.
2. Provider Accessibility: Verifies that the referenced secret provider is available and accessible within the target project.

Verification Logic

Method	Description
containsExternalSecrets	Identifies if $secrets expressions exist in the data object.
isChangingExternalSecretExpression	Compares new and existing data to see if expressions were added or modified.
validateAccessToReferencedSecretProviders	Checks project-level access for every provider key extracted from expressions.
Sources: packages/cli/src/credentials/validation.ts:17-38, packages/cli/src/credentials/validation.ts:89-125

Credential Types & UI

Credentials implement the ICredentialType interface, which defines their structure and authentication logic.

Credential Definition Properties

Property	Description
name	Internal identifier (e.g., notionApi).
displayName	Human-readable name.
properties	Input fields like API keys, client IDs, or passwords.
authenticate	Configuration for authentication (Generic or Custom).
test	A request used to verify the credential works.
Sources: packages/nodes-base/AGENTS.md:46-52

Authentication Modes

The frontend supports multiple authentication flows, including Managed OAuth2 (handled by n8n), Custom OAuth2 (user-provided client IDs), and standard API Keys.

Source Control & Stubs

When exporting workflows to source control, n8n handles credentials by creating "stubs." This process removes sensitive data while preserving the credential metadata and structure for portability.

Sanitization Process

1. Remove Sensitive Fields: The SourceControlExportService replaces values for keys like apiKey, clientSecret, and token with empty strings.
2. Exclude Tokens: OAuth oauthTokenData is completely removed from the exported JSON.
3. Preserve Non-Sensitive Types: Numbers and booleans (e.g., port numbers or SSL toggles) are typically preserved.
4. Ownership Metadata: The system adds ownedBy info (project ID, team name, or personal email) to the stub.

Sources: packages/cli/test/integration/environments/source-control-export.service.test.ts:109-128, packages/cli/test/integration/environments/source-control-export.service.test.ts:251-260

Security Guidelines for Developers

• Never use any: Always use ICredentialDataDecryptedObject or specific interfaces for credential data.
• Prototoype Pollution Prevention: When nodes use user input as computed keys for credentials, they must use setSafeObjectProperty from n8n-workflow to prevent prototype chain pollution.
• No PII in Logs: Do not log raw credential data or secrets.
• Credential Testing: Always implement a test method in ICredentialType to allow users to verify connections before use.

Sources: AGENTS.md:164, packages/nodes-base/AGENTS.md:113-120, packages/nodes-base/AGENTS.md:52

Credentials management in n8n balances user experience with rigorous encryption standards. By utilizing centralized cipher services and robust validation logic for both local and external secrets, the platform ensures that sensitive integration data remains secure throughout the workflow lifecycle.