Credentials System

The Credentials System in n8n provides a secure and structured way to store, manage, and utilize sensitive authentication data required by nodes to interact with third-party services. It ensures that secrets like API keys, tokens, and passwords are encrypted at rest and are only accessible within the context of a workflow execution. The system is designed to be flexible, supporting various authentication types, and is integrated with n8n's project and user management features for proper access control.

The core of the system involves encrypting user-provided data, storing it in the database, and providing a secure mechanism for nodes to retrieve and use this data during runtime. It also includes features for managing credentials through the UI and API, scoping them to specific projects, and safely exporting them for version control.

Core Components

The system is built upon several key components that work together to handle the lifecycle of a credential.

Credentials Class

The Credentials class is the primary in-memory representation of a credential. It encapsulates the credential's metadata and its encrypted data, providing methods to securely access and manipulate the sensitive information.

Key responsibilities:

• Holding credential metadata (id, name).
• Managing the encrypted data string.
• Decrypting data on-demand using the Cipher service.
• Encrypting and updating data.
• Handling decryption and parsing errors.

The diagram below shows the structure of the Credentials class.

CredentialsEntity

This is the TypeORM entity that defines the database schema for storing credentials. Each record in the credentials_entity table corresponds to a single saved credential.

The diagram below illustrates the entity relationship for credentials.

This diagram shows that each CredentialsEntity is associated with a Project.

Sources: packages/cli/test/integration/environments/source-control-export.service.test.ts:13-20, packages/testing/playwright/tests/ui/39-projects.spec.ts:43-48

Cipher Service

The Cipher service is responsible for the actual encryption and decryption of credential data. It uses the encryptionKey defined in the instance settings to perform symmetric encryption. This ensures that all sensitive data stored in the CredentialsEntity is encrypted at rest. The core Credentials class relies on this service to decrypt data only when getData() is called.

Sources: packages/core/src/tests/credentials.test.ts:10-12, packages/cli/test/integration/environments/source-control-export.service.test.ts:100-104

Credential Lifecycle

Creation and Encryption

When a user creates a new credential, the data is encrypted and stored in the database. This flow is typically initiated from the n8n UI, either from the credentials page or directly from a node's properties panel (Node Display View - NDV).

The sequence diagram below illustrates the credential creation process.

Data Retrieval and Decryption

During workflow execution, a node that requires authentication will retrieve the necessary credentials. The system decrypts the data just-in-time for the node to use.

The getData() method on the Credentials class orchestrates this. It checks if the data has already been decrypted; if not, it calls the Cipher service to decrypt the data string, parses the resulting JSON, and caches it for subsequent calls.

Error Handling

The getData() method includes robust error handling for common failure scenarios:

• CREDENTIAL_ERRORS.NO_DATA: Thrown if data is missing.
• CREDENTIAL_ERRORS.DECRYPTION_FAILED: Thrown if the Cipher service fails to decrypt the data, often due to a mismatched encryption key.
• CREDENTIAL_ERRORS.INVALID_JSON: Thrown if the decrypted string is not valid JSON.

Sources: packages/core/src/tests/credentials.test.ts:39-86

Project Scoping and Management

Credentials in n8n are scoped to Projects. A credential can belong to a user's "Personal" project or a shared "Team" project. This is managed via the projectId foreign key on the CredentialsEntity. This ensures that credentials created within a specific project are only available to workflows and users with access to that project.

Playwright tests demonstrate that the UI correctly filters credentials based on the current project context. It is also possible to move credentials between projects, which updates their projectId.

Sources: packages/testing/playwright/tests/ui/39-projects.spec.ts:43-53, 221-274

Default Credentials

When a node requiring a specific credential type is added to the canvas, n8n automatically selects a default credential if one of that type already exists in the current project. This streamlines the workflow building process by pre-populating the credential field.

Sources: packages/testing/playwright/tests/ui/2-credentials.spec.ts:217-224

Secure Export for Source Control

To support Git-based version control of workflows, n8n provides a mechanism to export credentials as "stubs". This process is handled by the SourceControlExportService. It exports the credential's metadata but sanitizes all sensitive data fields, replacing their values with empty strings. This allows the credential's structure and its link to a workflow to be versioned without exposing any secrets.

The exported JSON file includes an ownedBy object that specifies whether the credential belongs to a personal or team project, along with the relevant identifiers.

The following flowchart shows the credential export process.

Testing Credentials

Credentials are a critical part of testing nodes and workflows.

• Unit Tests: In node unit tests, getCredentials is typically mocked to return a predefined object, allowing the test to focus on the node's logic without needing a real database or encryption key.
• Workflow Tests: The NodeTestHarness used for workflow-level testing accepts a credentials object to simulate the presence of credentials required by the nodes in the test workflow.
• E2E Tests: Playwright tests interact with the full credential lifecycle, from creation in the UI to deletion, renaming, and usage within a node. These tests often use the API to set up or tear down credential data.

Sources: packages/nodes-base/TESTING_PROMPT_WORKFLOW.md, packages/testing/playwright/tests/ui/2-credentials.spec.ts, packages/core/src/tests/credentials.test.ts

Conclusion

The n8n Credentials System is a robust and secure framework for managing sensitive data. By combining strong encryption at rest, a clear data model, project-based scoping, and a well-defined lifecycle, it allows users to securely connect to thousands of services. Features like default credential selection, in-editor management, and sanitized exports for source control provide a seamless and developer-friendly experience while maintaining a high standard of security.