Credentials Management
Relevant source files
The following files were used as context for generating this wiki page:
- packages/cli/test/integration/credentials/credentials-overwrites.integration.test.ts
- packages/cli/test/integration/environments/source-control-export.service.test.ts
- packages/core/src/tests/credentials.test.ts
- packages/frontend/editor-ui/src/components/CredentialEdit/CredentialEdit.vue
- packages/testing/playwright/tests/ui/2-credentials.spec.ts
- packages/testing/playwright/tests/ui/39-projects.spec.ts
- packages/testing/playwright/tests/ui/credential-api-operations.spec.ts
- cypress/e2e/group6/17-sharing.cy.ts
- cypress/e2e/group6/34-template-credentials-setup.cy.ts
The Credentials Management system in n8n is responsible for securely storing, managing, and providing access to sensitive information like API keys, tokens, and login details required by workflow nodes to interact with third-party services. The system is designed with security as a priority, ensuring all sensitive data is encrypted at rest. It supports various authentication types, including OAuth1, OAuth2, and basic auth, and integrates with features like Projects for access control and Source Control for environment management.
This document outlines the architecture, data models, API, and key processes involved in managing credentials within the n8n platform.
Core Components and Architecture
The system is built around a few key components that handle data storage, encryption, and business logic.
| Component | Description | Source File |
|---|---|---|
CredentialsEntity | The TypeORM entity representing a credential in the database. It stores metadata and the encrypted data blob. | packages/db/src/entities/credentials-entity.ts |
Cipher | A core service responsible for encrypting and decrypting credential data using an instance-specific encryption key. | packages/core/src/encryption/cipher.ts |
Credentials (Core Class) | An in-memory representation of a credential. It handles the logic for accessing and manipulating encrypted data. | packages/core/src/__tests__/credentials.test.ts |
CredentialEdit.vue | The primary Vue component for creating and editing credentials in the user interface. | packages/frontend/editor-ui/src/components/CredentialEdit/CredentialEdit.vue |
CredentialsOverwrites | A service that handles overriding credential data, often from environment variables or a central configuration endpoint. | packages/cli/test/integration/credentials/credentials-overwrites.integration.test.ts |
SourceControlExportService | A service that manages exporting credentials for source control, ensuring sensitive data is sanitized. | packages/cli/test/integration/environments/source-control-export.service.test.ts |
Data Model
The CredentialsEntity is the central data structure for storing credential information in the database.
This diagram shows the basic structure of the CredentialsEntity table in the database.
Sources: packages/db/src/entities/credentials-entity.ts
Encryption and Decryption
All sensitive credential data is encrypted before being persisted to the database and decrypted only when needed for an execution. The Cipher service handles this process.
The following diagram illustrates the encryption and decryption flow.
The Credentials core class encapsulates this logic. When getData() is called, it retrieves the encrypted string and uses the Cipher service to decrypt it. If decryption or JSON parsing fails, it throws a CredentialDataError.
Sources: packages/core/src/tests/credentials.test.ts:74-114
Credential Lifecycle
Creation and Editing
Users can create and manage credentials through the UI, which is primarily handled by the CredentialEdit.vue component. This component provides a form for entering credential details, which are then sent to the backend API.
The following sequence diagram shows the flow for creating a new credential.
This diagram illustrates the process of a user creating a credential, from the UI to the API and finally to the database.
Sources: packages/frontend/editor-ui/src/components/CredentialEdit/CredentialEdit.vue:534-569, packages/testing/playwright/tests/ui/credential-api-operations.spec.ts:13-23
Key UI features in CredentialEdit.vue:
- Tabs: The modal is organized into "Connection", "Sharing", and "Details" tabs.
- Dynamic Forms: The form fields are dynamically rendered based on the
propertiesdefined in the credential type definition. - Testing: For non-OAuth credentials, a "Test" button is available to verify the connection.
- OAuth Flow: For OAuth1 and OAuth2, it initiates the authorization flow by opening a popup window.
- Saving: The
saveCredentialmethod handles both creating new and updating existing credentials.
Sources: packages/frontend/editor-ui/src/components/CredentialEdit/CredentialEdit.vue
Deletion
Credentials can be deleted from the UI or via the API. When a credential is deleted, any workflow that uses it may break. The UI presents a confirmation dialog to the user before proceeding.
Sources: packages/frontend/editor-ui/src/components/CredentialEdit/CredentialEdit.vue:614-650, packages/testing/playwright/tests/ui/2-credentials.spec.ts:133-144
API Operations
The backend exposes a set of RESTful endpoints for managing credentials.
| Method | Endpoint | Description |
|---|---|---|
POST | /rest/credentials | Creates a new credential. |
GET | /rest/credentials | Retrieves a list of credentials. Supports query parameters like includeData and filter. |
GET | /rest/credentials/:id | Retrieves a single credential by its ID. |
PUT | /rest/credentials/:id | Updates an existing credential. |
DELETE | /rest/credentials/:id | Deletes a credential. |
POST | /rest/credentials/:id/transfer | Transfers a credential to a different project. |
Sources: packages/testing/playwright/tests/ui/credential-api-operations.spec.ts
Advanced Features
Credential Overwrites
The CredentialsOverwrites service allows for overriding credential data at runtime. This is useful for environments where credentials are managed externally (e.g., via environment variables or a secrets manager).
- Persistence: Overwrites can be persisted to the database, controlled by the
credentials.overwrite.persistenceconfiguration flag. - API Endpoint: An endpoint (
/integration-credentials-overwrite) is available to update the overwrite data dynamically. - Data Loading: Overwrites are loaded from both static configuration and the database on initialization. The database version takes precedence.
- Pub/Sub Reload: The system uses a Pub/Sub mechanism to reload credentials on all instances when an update occurs, ensuring consistency in a multi-worker setup.
The flow for setting and reloading overwritten credentials is as follows:
Project Scoping and Sharing
Credentials can be associated with a specific project (either a user's personal project or a team project). This allows for better organization and access control.
- Filtering: The credentials API can filter credentials by
projectId. - Sharing: Credentials can be shared with other users or projects. When a workflow is shared, its associated credentials must also be accessible to the recipient for the workflow to function correctly.
- UI Behavior: In the workflow editor, the credential dropdown for a node only shows credentials that are available in the current project context (the project the workflow belongs to) or have been explicitly shared.
Sources: packages/testing/playwright/tests/ui/39-projects.spec.ts:14-26, cypress/e2e/group6/17-sharing.cy.ts
Source Control Export
When workflows are exported for source control, the associated credentials are also exported as "stubs". To prevent leaking sensitive information, the SourceControlExportService sanitizes the credential data.
The sanitization process works as follows:
- The service retrieves the full credential, including the encrypted data.
- It decrypts the data to access its structure.
- It iterates through the properties of the decrypted data object.
- It replaces all string values with an empty string (
''), effectively removing secrets. Numbers and booleans are preserved. - The
oauthTokenDatafield, which contains sensitive OAuth tokens, is completely excluded from the exported stub. - The sanitized data object is then written to a JSON file.
This process ensures that the structure of the credential is preserved for import on another instance, but no sensitive values are committed to the Git repository.
Conclusion
The n8n Credentials Management system provides a robust and secure way to handle sensitive data. By leveraging strong encryption, clear data models, and a well-defined API, it ensures that credentials are both safe and easy to use within workflows. Advanced features like project-based scoping, sharing, runtime overwrites, and safe source control integration make it a flexible solution for both individual developers and large teams managing complex automation environments.