npm package: @fpossebon/n8n-nodes-infisical
Description: n8n community node for Infisical secret management - supports Get Secret and List Secrets operations with multiple authentication methods
Author: possebon
Latest version: 0.1.0

# 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](./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](./DEVELOPMENT.md) for:
- Local development setup
- Testing procedures
- Build and packaging
- Contribution guidelines

## API Reference

- [Infisical API Documentation](https://infisical.com/docs/api-reference/overview/introduction)
- [Universal Auth API](https://infisical.com/docs/documentation/platform/identities/universal-auth)
- [API Keys Documentation](https://infisical.com/docs/api-reference/overview/authentication)

## 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](https://infisical.com/docs).