n8n-nodes-ferentin

Official n8n node for Ferentin AI - Enterprise-grade AI integration with OAuth2 and OpenTelemetry

This is an n8n community node that provides native integration with Ferentin AI's OpenAI-compatible API. It lets you use Ferentin AI models in your n8n workflows with enterprise-grade security and observability.

Features

• OAuth2 Authentication - Secure, token-based authentication (no API keys to manage)
• Dynamic Model Discovery - Automatically fetches available models from your Ferentin instance
• OpenTelemetry Support - Native W3C trace context for end-to-end observability
• Streaming & JSON Modes - Choose between real-time streaming or standard JSON responses
• Comprehensive Error Handling - Automatic retries, detailed error messages, and graceful degradation
• Full Parameter Control - Temperature, tokens, penalties, stop sequences, and more
• TypeScript & Tested - Fully typed with comprehensive test coverage

Installation

In n8n (Community Nodes)

1. Go to Settings → Community Nodes
2. Click Install
3. Enter n8n-nodes-ferentin
4. Click Install
5. Restart n8n

Manual Installation

# Navigate to your n8n installation
cd ~/.n8n/nodes

# Install the package
npm install n8n-nodes-ferentin --legacy-peer-deps

# Restart n8n

For Development

# Clone the repository
git clone https://github.com/ferentin/n8n-nodes-ferentin.git
cd n8n-nodes-ferentin

# Install dependencies
npm install --legacy-peer-deps

# Build the project
npm run build

# Run tests
npm test

# Development mode with hot reload
npm run dev

Compatibility

• n8n version: 1.0.0 or later
• Node.js version: 22.0.0 or later
• Ferentin API: OpenAI-compatible v1 endpoints

Quick Start

1. Set Up OAuth2 Credentials

1. In n8n, go to Credentials → New
2. Search for "Ferentin OAuth2 API"
3. Fill in your OAuth2 configuration:
   • Authorization URL: Your Ferentin OAuth2 authorize endpoint
   • Access Token URL: Your Ferentin OAuth2 token endpoint
   • Client ID: Your OAuth2 client ID
   • Client Secret: Your OAuth2 client secret
   • Scope: llm (required)
4. Click Connect my account
5. Complete the OAuth2 flow in the popup window
6. Click Save

2. Add Ferentin Node to Workflow

1. Create or open a workflow
2. Click + to add a new node
3. Search for "Ferentin"
4. Select the Ferentin node
5. Choose your saved credentials
6. Configure the node (see examples below)

Usage Examples

Example 1: Simple Chat Completion

Create a basic AI chat response:

// Node Configuration
Operation: Chat
Model: [Select from dropdown]
Messages:
  - Role: system
    Content: You are a helpful AI assistant.
  - Role: user
    Content: What is the capital of France?
Response Mode: JSON

Output:

{
  "content": "The capital of France is Paris.",
  "role": "assistant",
  "finishReason": "stop",
  "model": "ferentin-model-name",
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28
  }
}

Example 2: Multi-Message Conversation

Build context with conversation history:

Messages:
  - Role: system
    Content: You are a customer support agent for Acme Corp.
  - Role: user
    Content: I can't log into my account
  - Role: assistant
    Content: I'd be happy to help. Have you tried resetting your password?
  - Role: user
    Content: Yes, but I'm not receiving the email

Example 3: Using Advanced Parameters

Fine-tune the AI response:

Operation: Chat
Model: ferentin-gpt-4
Messages:
  - Role: user
    Content: Write a creative product description for wireless headphones

Options:
  Temperature: 1.5          // More creative
  Maximum Tokens: 200       // Limit response length
  Top P: 0.9
  Frequency Penalty: 0.5    // Reduce repetition
  Presence Penalty: 0.3     // Encourage topic diversity
  Stop Sequences: \\n\\n, END

Example 4: With OpenTelemetry Tracing

Enable distributed tracing for production observability:

Options:
  Enable Tracing: true
  Trace Parent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
  // Format: 00-{trace-id}-{span-id}-{flags}

The traceparent header will be sent to Ferentin API, enabling end-to-end request tracing across your infrastructure.

Example 5: Streaming Mode (Real-time)

Get responses as they're generated:

Response Mode: Streaming

// Note: Streaming mode will output tokens as they arrive
// Useful for real-time chat interfaces

Workflow Examples

Customer Support Automation

Trigger (Webhook - Customer Email)
  ↓
Ferentin (Analyze sentiment + categorize)
  ↓
Switch (Route based on sentiment)
  ↓
Ferentin (Generate response)
  ↓
Gmail (Send reply)
  ↓
Slack (Notify team if escalation needed)

Content Generation Pipeline

Google Sheets (Get topics)
  ↓
Loop (For each topic)
  ↓
Ferentin (Research + outline)
  ↓
Ferentin (Write article)
  ↓
Grammarly API (Proofread)
  ↓
WordPress (Publish)

Data Enrichment

PostgreSQL (Fetch customer records)
  ↓
Ferentin (Extract entities, classify, summarize)
  ↓
PostgreSQL (Update with AI insights)
  ↓
Trigger downstream workflows

Configuration Reference

Operation: Chat

Creates a chat completion using the Ferentin AI API.

Required Parameters

Parameter	Type	Description
Model	Dropdown	Ferentin model to use (dynamically loaded)
Messages	Collection	Array of conversation messages

Message Structure

Field	Options	Description
Role	system, user, assistant	Message sender role
Content	String	Message text content

Optional Parameters

Parameter	Type	Range	Default	Description
Temperature	Number	0.0 - 2.0	1.0	Sampling randomness
Maximum Tokens	Number	1+	unlimited	Max tokens to generate
Top P	Number	0.0 - 1.0	1.0	Nucleus sampling
Frequency Penalty	Number	-2.0 - 2.0	0.0	Penalize token frequency
Presence Penalty	Number	-2.0 - 2.0	0.0	Penalize token presence
Stop Sequences	String	-	empty	Comma-separated stop tokens
Enable Tracing	Boolean	-	false	Include OTEL headers
Trace Parent	String	W3C format	empty	Trace context header
Request Timeout	Number	1000+ ms	60000	Request timeout

Response Mode

Mode	Description	Use Case
JSON	Standard request/response	Batch processing, data transformation
Streaming	Real-time token streaming	Chat interfaces, progress monitoring

Output Schema

Success Response (JSON Mode)

{
  content: string;           // AI-generated text
  role: string;              // "assistant"
  finishReason: string;      // "stop", "length", or stop sequence
  message: {
    role: string;
    content: string;
  };
  model: string;             // Model used
  id: string;                // Completion ID
  created: number;           // Unix timestamp
  usage?: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
  input: {                   // Your input for reference
    messages: Array<Message>;
    model: string;
    responseMode: string;
  };
}

Error Handling

The node provides detailed error messages for common scenarios:

Status Code	Error Message	Action
401	Authentication failed. Please reconnect your Ferentin OAuth2 credentials.	Reconnect OAuth2
403	Insufficient permissions. Ensure "llm" scope is granted.	Check OAuth2 scopes
429	Rate limit exceeded. Request will retry automatically.	Wait for retry
400	Invalid request: {details}. Check model selection and message format.	Fix parameters
500+	Ferentin API error ({code}): {message}	Check API status

Automatic Retry Logic

• 401 Unauthorized: Triggers OAuth2 token refresh
• 429 Rate Limit: 3 retries with exponential backoff
• 500 Server Error: 2 retries with backoff
• Network Errors: 3 retry attempts

Advanced Topics

Using with LangChain (Future)

This node is designed to integrate with n8n's LangChain nodes in future releases.

Multi-Model Workflows

You can use multiple Ferentin nodes in a single workflow with different models:

Input Data
  ↓
Ferentin (fast-model) → Quick analysis
  ↓
Ferentin (advanced-model) → Detailed processing
  ↓
Combine Results

Dynamic Parameter Expressions

All parameters support n8n expressions:

// Dynamic message from previous node
Content: {{ $json.userQuestion }}

// Conditional temperature
Temperature: {{ $json.creative ? 1.5 : 0.3 }}

// Dynamic model selection
Model: {{ $json.complexity === 'high' ? 'gpt-4' : 'gpt-3.5-turbo' }}

Trace Context Propagation

Generate trace IDs in your workflow:

// Code node before Ferentin
const traceId = crypto.randomBytes(16).toString('hex');
const spanId = crypto.randomBytes(8).toString('hex');
return [{
  json: {
    traceParent: `00-${traceId}-${spanId}-01`
  }
}];

// Then reference in Ferentin node
Trace Parent: {{ $json.traceParent }}

Troubleshooting

Models dropdown is empty

Cause: OAuth2 credentials not connected or invalid scope
Solution:

1. Reconnect your OAuth2 credentials
2. Ensure llm scope is granted
3. Check that your Ferentin API is accessible

"Authentication failed" error

Cause: OAuth2 token expired or invalid
Solution: Reconnect your credentials in n8n

Request timeout

Cause: Model taking too long to respond
Solution: Increase timeout in Options or reduce maxTokens

Streaming not working

Cause: Streaming requires special handling
Solution: Check your Ferentin API supports streaming. Use JSON mode for standard workflows.

Rate limit errors

Cause: Too many requests to Ferentin API
Solution: Node will auto-retry. Consider adding delays between requests.

Development

Project Structure

n8n-nodes-ferentin/
├── credentials/
│   └── FerentinOAuth2Api.credentials.ts
├── nodes/
│   └── Ferentin/
│       ├── Ferentin.node.ts
│       ├── ferentin.svg
│       └── __tests__/
│           └── Ferentin.node.test.ts
├── package.json
├── tsconfig.json
└── README.md

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

Building

# TypeScript compilation
npm run build

# Watch mode for development
npm run build:watch

# Linting
npm run lint
npm run lint:fix

# Formatting
npm run format
npm run format:check

Publishing

# Update version in package.json
npm version patch|minor|major

# Build and publish
npm run build
npm publish

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Security

Reporting Vulnerabilities

Please report security vulnerabilities to: security@ferentin.net

OAuth2 Best Practices

• Never commit OAuth2 credentials to version control
• Rotate client secrets regularly
• Use minimal scopes (only llm is required)
• Enable audit logging in production

Support

• Documentation: https://docs.ferentin.net/n8n
• Issues: https://github.com/ferentin/n8n-nodes-ferentin/issues
• Community: https://community.n8n.io
• Email: support@ferentin.net

License

MIT

Copyright (c) 2025 Ferentin

Acknowledgments

• Built with the n8n node development kit
• OpenAI API compatibility for seamless integration
• Inspired by the n8n community's excellent work

Changelog

See CHANGELOG.md for release history.

---

Made with ❤️ by Ferentin

Website • Documentation • Community