n8n Integration Guide
Reference for the OpenBox n8n integration — the governance pipeline, configuration options, error handling, and additional examples.
Run the n8n Demo for a hands-on walkthrough, or Wrap an Existing n8n Workflow to add governance to your own workflow.
Prerequisites
- Completed the n8n demo or wrapped an existing workflow
- An OpenBox API key. Register an agent in the OpenBox Dashboard to obtain one.
Customising the Node
Change the LLM provider
Replace the Ollama call inside the activity callback. The SDK doesn't care what the activity does — it governs the data going in and coming out.
import { govern } from 'openbox';
const { output, meta } = await govern(
transport,
{ apiKey, activityType: 'OpenAIChat' },
'N8nChatWorkflow',
{ chatInput: userMessage },
async (governed) => {
const response = await helpers.httpRequest({
method: 'POST',
url: 'https://api.openai.com/v1/chat/completions',
headers: { Authorization: `Bearer ${openaiKey}` },
body: {
model: 'gpt-4o',
messages: [
{ role: 'system', content: systemPrompt },
{ role: 'user', content: (governed as any).chatInput },
],
},
});
return { text: (response as any).choices[0].message.content };
},
);
Fail-closed governance
govern(transport, { apiKey, activityType, governancePolicy: 'fail_closed' }, ...);
Human-in-the-loop
govern(transport, { apiKey, activityType, hitlEnabled: true }, ...);
When governance returns require_approval, the SDK polls the dashboard until a human approves or rejects.
How It Works
govern() wraps your LLM call through a 5-stage pipeline:
Verdicts at each checkpoint:
| Verdict | Behavior |
|---|---|
allow | Proceeds unmodified |
constrain | Input or output is redacted; call proceeds with cleaned data |
require_approval | Pauses until a human approves via the dashboard |
block | Terminated, error returned |
halt | Call and enclosing workflow terminated |
What gets checked at each stage is configured in the OpenBox Dashboard — no code changes needed.
Configuration Reference
Options passed to govern():
| Option | Default | Description |
|---|---|---|
apiKey | Required | Your OpenBox API key (obx_live_* or obx_test_*) |
apiEndpoint | https://core.openbox.ai | OpenBox Core base URL |
activityType | LlmActivity | Must match the dashboard config |
governancePolicy | fail_open | Set to fail_closed to block when Core is unreachable |
hitlEnabled | false | Enable human-in-the-loop approval |
hitlPollInterval | 5 | Polling interval in seconds while waiting for approval |
hitlMaxWait | 300 | Maximum wait time for approval in seconds |
apiTimeout | 30 | Request timeout in seconds |
Error Handling
When governance blocks a request, the user sees an error. Possible outcomes:
| Error | Cause |
|---|---|
GuardrailsValidationError | Input or output failed a check (PII, toxicity, etc.) |
GovernanceBlockedError | A policy rule blocked the action |
ApprovalExpiredError | HITL request timed out |
ApprovalRejectedError | A human reviewer rejected the request |
ApprovalDisabledError | Verdict requires approval but HITL is not enabled |
To catch these in code:
const {
GovernanceBlockedError,
GuardrailsValidationError,
ApprovalExpiredError,
ApprovalRejectedError,
ApprovalDisabledError,
} = require('openbox');
try {
const { output } = await govern(transport, config, workflow, input, callback);
} catch (err) {
if (err instanceof GuardrailsValidationError) { /* guardrail failed */ }
if (err instanceof GovernanceBlockedError) { /* policy blocked */ }
if (err instanceof ApprovalExpiredError) { /* HITL timed out */ }
if (err instanceof ApprovalRejectedError) { /* HITL rejected */ }
if (err instanceof ApprovalDisabledError) { /* HITL not enabled */ }
}
Next Steps
- Configure guardrails — PII detection, toxicity filtering, banned terms, content classification
- Set up policies — authorization rules, risk thresholds, data classification
- Enable approvals — human-in-the-loop workflows for sensitive operations
- View sessions — monitor governed interactions in the dashboard event timeline