n8n Setup Guide

Connect n8n to K0nsult in 6 steps. Estimated time: 20 minutes.

1 Install n8n

Option A: Self-hosted (Docker)

docker run -d --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  -e N8N_BASIC_AUTH_ACTIVE=true \
  -e N8N_BASIC_AUTH_USER=admin \
  -e N8N_BASIC_AUTH_PASSWORD=your-secure-password \
  n8nio/n8n

Option B: n8n Cloud

Sign up at n8n.io and create a new instance. No installation required.

2 Add Pre-Check Node (Policy Gate)

In your n8n workflow, add an HTTP Request node at the beginning to validate the workflow against K0nsult policies before proceeding.

HTTP Request Node Configuration

{
  "method": "POST",
  "url": "https://k0nsult.fly.dev/api/n8n/pre-check",
  "headers": {
    "Content-Type": "application/json",
    "x-konsult-secret": "{{ $env.KONSULT_API_KEY }}"
  },
  "body": {
    "workflow_id": "{{ $workflow.id }}",
    "workflow_name": "{{ $workflow.name }}",
    "user": "{{ $execution.customData?.user || 'system' }}",
    "data_classification": "internal",
    "action_type": "read"
  }
}

Add an IF Node After Pre-Check

// IF condition — only proceed if approved
{{ $json.decision }} === "APPROVE"

// True branch  → continue workflow
// False branch → route to escalation or stop

3 Configure Execution Logging

Add an HTTP Request node at the end of your workflow (or in an error handler) to log the execution result back to K0nsult.

Success Path — Final Node

{
  "method": "POST",
  "url": "https://k0nsult.fly.dev/api/n8n/execution-log",
  "headers": {
    "Content-Type": "application/json",
    "x-konsult-secret": "{{ $env.KONSULT_API_KEY }}"
  },
  "body": {
    "workflow_id": "{{ $workflow.id }}",
    "workflow_name": "{{ $workflow.name }}",
    "status": "COMPLETED",
    "duration_ms": "{{ Date.now() - $execution.startedAt }}",
    "nodes_executed": "{{ $execution.nodes.length }}",
    "output_summary": "Workflow completed successfully"
  }
}

Error Handler — Catch Node

{
  "method": "POST",
  "url": "https://k0nsult.fly.dev/api/n8n/execution-log",
  "body": {
    "workflow_id": "{{ $workflow.id }}",
    "workflow_name": "{{ $workflow.name }}",
    "status": "FAILED",
    "duration_ms": "{{ Date.now() - $execution.startedAt }}",
    "error": "{{ $json.error?.message || 'Unknown error' }}"
  }
}

4 Set Up Escalation Node

When the pre-check returns "decision": "REVIEW" or "decision": "DENY", route the workflow to an escalation node that notifies K0nsult.

Escalation HTTP Request

{
  "method": "POST",
  "url": "https://k0nsult.fly.dev/api/n8n/escalate",
  "headers": {
    "Content-Type": "application/json",
    "x-konsult-secret": "{{ $env.KONSULT_API_KEY }}"
  },
  "body": {
    "workflow_id": "{{ $workflow.id }}",
    "workflow_name": "{{ $workflow.name }}",
    "reason": "Pre-check returned REVIEW — manual approval required",
    "severity": "high",
    "context": {
      "risk_score": "{{ $node['Pre-Check'].json.risk_score }}",
      "level": "{{ $node['Pre-Check'].json.level }}",
      "user": "{{ $execution.customData?.user || 'system' }}"
    }
  }
}

Severity Levels

• critical — maps to P1 (5-minute SLA)
• high — maps to P2 (30-minute SLA)
• anything else — maps to P3 (4-hour SLA)

5 Test with a Sample Workflow

Create a simple test workflow to verify the integration end-to-end.

Workflow Structure

[Manual Trigger]
    |
[HTTP Request: Pre-Check]  --> POST /api/n8n/pre-check
    |
[IF: decision === APPROVE]
    |            |
  [True]       [False]
    |            |
[Your Logic]  [HTTP Request: Escalate]
    |
[HTTP Request: Execution Log]  --> POST /api/n8n/execution-log

Test Commands (cURL)

Test 1: Low-risk workflow (should auto-approve)

curl -X POST https://k0nsult.fly.dev/api/n8n/pre-check \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "test-001",
    "workflow_name": "Test Low Risk",
    "user": "admin",
    "data_classification": "internal",
    "action_type": "read"
  }'

# Expected: { "decision": "APPROVE", "risk_score": 2, "level": "A" }

Test 2: High-risk workflow (should require review)

curl -X POST https://k0nsult.fly.dev/api/n8n/pre-check \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "test-002",
    "workflow_name": "Test PII Access",
    "user": "admin",
    "data_classification": "PII",
    "action_type": "modify"
  }'

# Expected: { "decision": "REVIEW", "risk_score": 6, "level": "C" }

Test 3: Blocked workflow (should deny)

curl -X POST https://k0nsult.fly.dev/api/n8n/pre-check \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "test-003",
    "workflow_name": "Test Regulated Delete",
    "user": "admin",
    "data_classification": "regulated",
    "action_type": "delete"
  }'

# Expected: { "decision": "DENY", "risk_score": 9, "level": "D" }

6 Verify Audit Trail in K0nsult

After running the test commands, verify that the decisions appear in the K0nsult dashboard.

Check via API

curl https://k0nsult.fly.dev/api/n8n/audit/test-001

# Returns all audit entries for workflow test-001

Check via Dashboard

1. Open K0nsult Orchestration Dashboard
2. Look for your test workflow entries in the Execution Log panel
3. Verify risk scores and decisions match expected values
4. Check the Risk Heatmap for visual confirmation

Retrieve Policy

curl https://k0nsult.fly.dev/api/n8n/policy/test-001

# Returns the default policy with allowed/blocked actions, SLAs, and thresholds