Credentials & Secrets
Relevant source files
The following files were used as context for generating this wiki page:
- packages/cli/src/credentials/validation.ts
- packages/frontend/editor-ui/src/features/credentials/components/CredentialEdit/CredentialConfig.vue
- packages/@n8n/instance-ai/skills/workflow-builder/references/credential-recipe-research.md
- packages/cli/test/integration/environments/source-control-export.service.test.ts
- packages/nodes-base/AGENTS.md
- packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md
The Credentials & Secrets system manages sensitive information required to connect n8n nodes to external services and APIs. It provides a secure layer for storing, validating, and referencing authentication data such as API keys, OAuth2 tokens, and external secrets from third-party vaults.
Sources: packages/@n8n/node-cli/src/template/templates/shared/default/AGENTS.md, packages/frontend/editor-ui/src/features/credentials/components/CredentialEdit/CredentialConfig.vue
Credential Structure and Types
Credentials implement the ICredentialType interface. Each credential contains metadata for display in the UI and technical properties for authentication.
Core Components
| Component | Description |
|---|---|
| Name | Internal identifier for the credential type. |
| DisplayName | Human-readable name shown in the n8n interface. |
| Properties | Array of INodeProperties defining the fields (e.g., API Key, User, Password). |
| Authenticate | Configuration for the authentication method (e.g., Header, Query, OAuth2). |
| Test | Request configuration used to verify if the credential works. |
Sources: packages/nodes-base/AGENTS.md:46-52
Authentication Modes
The system supports multiple authentication strategies:
- Simple Auth: Basic fields like API keys or username/password.
- OAuth2: Managed flows including
accessTokenUrl,clientId, andclientSecret. - External Secrets: References to values stored in external vaults (e.g., HashiCorp Vault, AWS Secrets Manager).
- Templated Custom Auth: A guided form where users fill markers defined in an authentication template.
Sources: packages/frontend/editor-ui/src/features/credentials/components/CredentialEdit/CredentialConfig.vue:227-248, packages/cli/src/credentials/validation.ts:13-15
Validation and Security
The system enforces strict validation logic during the creation and modification of credentials.
External Secrets Validation
When a credential references external secrets (indicated by the $secrets expression), the system performs the following checks:
- Permission Check: Validates if the user has
externalSecret:listscopes for the specific project. - Provider Access: Ensures the project has access to the referenced external secret providers.
- Expression Extraction: Parses strings to find valid vault names within the expressions.
Sources: packages/cli/src/credentials/validation.ts:46-105
Data Sanitization for Export
When exporting credentials via Source Control, the system sanitizes sensitive data. It replaces actual secrets with empty strings while preserving non-sensitive fields and structure.
Credential Recipes and Research
Credential recipes allow for Simplified Custom Auth. To ensure accuracy, the system follows a research procedure to source authentication details from official provider documentation.
Research Workflow
- Auth Scheme: Identifies if the service uses headers (e.g.,
Authorization: Bearer), query parameters, or basic auth. - Key Page: Locates the specific URL where users generate or copy API keys (e.g.,
console.service.com/settings). - Verification Endpoint: Identifies a side-effect-free GET request (like
/meor/usage) that returns a 401/403 status code if the key is invalid.
Sources: packages/@n8n/instance-ai/skills/workflow-builder/references/credential-recipe-research.md:16-56
UI Components and Interaction
The CredentialConfig.vue component handles the rendering and state management of the credential editor.
Feature Interactions
- Connection Testing: Users can trigger a re-test of the credential. A successful test for templated auth displays an "Auth probe accepted" message.
- OAuth Management: Provides buttons for "Connect", "Switch Account", and "Disconnect" for OAuth2 types.
- AI Assistant Integration: Offers an "Ask AI Assistant" button to provide setup instructions based on the credential type and documentation URL.
- Project Scoping: Credentials are tied to projects. In team projects, the UI displays banners if a credential is not yet connected by the current user.
Sources: packages/frontend/editor-ui/src/features/credentials/components/CredentialEdit/CredentialConfig.vue:245-255, packages/frontend/editor-ui/src/features/credentials/components/CredentialEdit/CredentialConfig.vue:464-500
Connection States
| State | UI Representation |
|---|---|
| Successful | Success banner with message "Account connected" or "Connected as [Account]". |
| Not Connected | Warning/Info banner with a "Connect" button. |
| Stale | Danger banner indicating connection failure, prompting "Switch Account" or "Retry". |
| Validation Error | Danger banner requesting the user check errors in specific fields. |
Sources: packages/frontend/editor-ui/src/features/credentials/components/CredentialEdit/CredentialConfig.vue:152-192, packages/frontend/editor-ui/src/features/credentials/components/CredentialEdit/CredentialConfig.vue:410-450
Conclusion
The Credentials & Secrets system balances ease of use with enterprise-grade security. By integrating external secret providers and rigorous validation during data exports, it ensures that sensitive information remains protected while providing developers with a streamlined interface for managing service authentications.
Sources: packages/cli/src/credentials/validation.ts, packages/cli/test/integration/environments/source-control-export.service.test.ts