n8n-nodes-infisical

n8n community node for integrating with Infisical secret management platform.

Features

Operations

• Get Secret: Retrieve a single secret by name with optional metadata
• List Secrets: Retrieve multiple secrets with filtering (wildcard patterns, tags) and sorting

Authentication

• Multiple authentication methods: Universal Auth (Machine Identity), API Keys, Service Tokens, and JWT
• Automatic token refresh for Universal Auth and JWT methods
• Dynamic credential form fields based on selected authentication method
• Optional project scoping for streamlined workflow configuration
• Comprehensive connection testing with clear error messaging
• Secure credential storage using n8n's built-in encryption

AI Agent Integration

• MCP (Model Context Protocol) tool integration for AI agents
• Use with n8n's Langchain nodes for AI-powered secret management workflows

Installation

Community Node Installation (n8n Cloud & Self-hosted)

1. In your n8n instance, go to Settings > Community Nodes
2. Click "Install" and enter: @fpossebon/n8n-nodes-infisical
3. Click "Install" and wait for the installation to complete
4. The Infisical node will appear in your node palette

Note: n8n Cloud may require approval for community nodes. For self-hosted instances, ensure N8N_COMMUNITY_PACKAGES_ENABLED=true is set in your environment variables.

Manual Installation (Development)

See DEVELOPMENT.md for local development setup instructions.

Authentication Methods

Universal Auth (Machine Identity) - Recommended

Universal Auth is the recommended authentication method offering:

• Automatic token refresh (tokens typically expire after 2 hours)
• Token renewal up to 30 days without re-authentication
• Enhanced security through short-lived access tokens

Setup:

1. In Infisical, navigate to Project Settings > Machine Identities
2. Create a new Machine Identity
3. Copy the Client ID and Client Secret
4. In n8n, create new Infisical API credentials
5. Select "Universal Auth (Machine Identity)" as the authentication method
6. Paste your Client ID and Client Secret
7. Test the connection

API Key Authentication (Legacy)

Note: API Keys are being deprecated by Infisical. Consider migrating to Universal Auth.

Setup:

1. In Infisical, navigate to Project Settings > API Keys
2. Generate a new API Key
3. In n8n, create new Infisical API credentials
4. Select "API Key" as the authentication method
5. Paste your API Key
6. Test the connection

Service Token Authentication (Legacy)

Note: Service Tokens are being deprecated by Infisical. Consider migrating to Universal Auth.

Setup:

1. In Infisical, navigate to Project Settings > Service Tokens
2. Generate a new Service Token
3. In n8n, create new Infisical API credentials
4. Select "Service Token" as the authentication method
5. Paste your Service Token
6. Test the connection

JWT Authentication

JWT-based authentication for advanced use cases.

Setup:

1. Obtain a valid JWT token from your authentication provider
2. In n8n, create new Infisical API credentials
3. Select "JWT Authentication" as the authentication method
4. Paste your JWT token
5. Test the connection

Configuration

Instance URL

The HTTPS URL to your Infisical instance. For Infisical Cloud, use https://app.infisical.com. For self-hosted instances, use your custom domain.

Requirements:

• Must use HTTPS protocol
• Must not have a trailing slash
• Example: https://app.infisical.com

Project Slug/ID (Optional)

When provided, all operations using this credential will automatically scope to the specified project. When left empty, nodes will prompt for the project on each operation.

Use cases:

• Project-specific credential: Set a project slug/ID to create a credential dedicated to one project
• Multi-project credential: Leave empty to use the same credential across multiple projects

Architecture

Credential Class

The InfisicalApi credential class implements n8n's ICredentialType interface with:

• Dynamic form fields using displayOptions for conditional visibility
• Deprecation warnings for legacy authentication methods
• Security messaging about encrypted credential storage
• Comprehensive field descriptions and placeholder text

Authentication Flow

Universal Auth Flow

1. User provides Client ID and Client Secret
2. InfisicalApiClient calls /api/v1/auth/universal-auth/login
3. Receives access token with expiration metadata
4. Stores token metadata securely with credential
5. Before each API call, checks if token is near expiration (>80% TTL)
6. If near expiration, calls /api/v1/auth/token/renew
7. On renewal failure, re-authenticates using original credentials

API Key/Service Token Flow

1. User provides static API Key or Service Token
2. Token is stored securely with credential
3. For each API call, token is added to Authorization header
4. No token refresh required (static credentials)

JWT Auth Flow

1. User provides JWT token
2. Token is validated for basic JWT structure
3. For each API call, JWT is added to Authorization header
4. Token refresh logic applies if JWT returns renewable access token

Token Refresh Mechanism

For Universal Auth and JWT methods:

• Tokens are checked before each API request
• Refresh triggers when 80% of token TTL has elapsed
• Example: 7200s (2 hour) TTL → refresh at 5760s (1h 36m)
• Prevents token expiration during long-running workflows
• Automatic re-authentication fallback on renewal failure

Connection Testing Strategy

Connection tests validate:

1. Instance URL format (HTTPS, no trailing slash)
2. Credential field completeness (required fields present)
3. Network connectivity to Infisical instance
4. Credential validity through API call

Test endpoints by authentication method:

• Universal Auth: POST /api/v1/auth/universal-auth/login
• API Key: GET /api/v3/workspaces with Bearer token
• Service Token: GET /api/v3/workspaces with Bearer token
• JWT Auth: GET /api/v3/workspaces with Bearer token

Error handling:

• 401/403: "Authentication failed. Please verify your credentials."
• Network timeout: "Connection timeout. Please check your network and Instance URL."
• 404: "Cannot connect to Infisical instance. Please verify the Instance URL."
• 500: "Infisical server error. Please try again later."

Common Usage Examples

Example 1: Project-Specific Credential

Create a credential dedicated to one project:

Authentication Method: Universal Auth
Instance URL: https://app.infisical.com
Project Slug/ID: my-production-secrets
Client ID: <your-client-id>
Client Secret: <your-client-secret>

Now all nodes using this credential automatically operate on the my-production-secrets project.

Example 2: Multi-Project Credential

Create a credential for use across multiple projects:

Authentication Method: Universal Auth
Instance URL: https://app.infisical.com
Project Slug/ID: (leave empty)
Client ID: <your-client-id>
Client Secret: <your-client-secret>

Nodes using this credential will prompt for the project slug/ID on each operation.

Example 3: Self-Hosted Infisical

Connect to a self-hosted Infisical instance:

Authentication Method: Universal Auth
Instance URL: https://secrets.mycompany.com
Project Slug/ID: internal-apis
Client ID: <your-client-id>
Client Secret: <your-client-secret>

Error Messages and Troubleshooting

"Authentication failed. Please verify your credentials."

Cause: Invalid Client ID/Secret, API Key, Service Token, or JWT.

Solution:

• Double-check credentials in Infisical dashboard
• Ensure credentials haven't been revoked or expired
• Verify you're using credentials from the correct Infisical project

"Cannot connect to Infisical instance. Please verify the Instance URL."

Cause: Invalid Instance URL or network connectivity issue.

Solution:

• Verify Instance URL is correct (e.g., https://app.infisical.com)
• Ensure URL uses HTTPS protocol
• Remove trailing slash from URL if present
• Check network connectivity to Infisical instance
• For self-hosted instances, verify the instance is accessible

"Connection timeout. Please check your network and Instance URL."

Cause: Network timeout reaching Infisical instance.

Solution:

• Check your internet connection
• Verify firewall/proxy settings allow connections to Infisical
• For self-hosted instances, ensure instance is running and accessible

"Token renewal failed. Please re-authenticate."

Cause: Automatic token refresh failed and re-authentication also failed.

Solution:

• Edit the credential and test connection again
• Verify Client ID and Client Secret are still valid
• Check if credentials have been revoked in Infisical dashboard
• Consider creating new Machine Identity credentials

"Instance URL must use HTTPS protocol"

Cause: Instance URL uses HTTP instead of HTTPS.

Solution:

• Change URL to use HTTPS (e.g., change http:// to https://)
• Infisical requires HTTPS for security

"Instance URL must not have a trailing slash"

Cause: Instance URL ends with /.

Solution:

• Remove the trailing slash from the URL
• Example: Change https://app.infisical.com/ to https://app.infisical.com

Development

See DEVELOPMENT.md for:

• Local development setup
• Testing procedures
• Build and packaging
• Contribution guidelines

API Reference

• Infisical API Documentation
• Universal Auth API
• API Keys Documentation

License

MIT

Support

For issues and feature requests, please file an issue on the GitHub repository.

For Infisical-specific questions, refer to the Infisical Documentation.