---
title: Protect n8n workflows and AI agents
description: Install the Veefore node in your own n8n, route protected actions through Veefore, and let Veefore verify the instance for paths around it.
---
This guide connects an n8n instance **you operate** to Veefore. Do the
[shared setup](/build/connect-agents) first (agent, tool, policy, enforcement).
The runtime's **Connect** tab in the console shows these steps with your ids
filled in. For a deployment
Veefore controls, see [Veefore-managed n8n](/operate/managed-n8n).

Two things happen once it is set up:

- Workflows and AI agents perform protected actions through the **Veefore
  node**. The gateway runs policy, risk, approval and the credential broker,
  and performs the call itself. The workflow never holds the provider secret.
- Veefore **verifies the instance** through the n8n API: it reads workflow
  definitions and credential metadata and reports every path that acts outside
  Veefore — a direct Gmail node, a generic HTTP Request, a Code node, a provider
  credential stored in n8n.

:::warning What Veefore can and cannot promise on your instance
You keep administrator access to your own n8n. Anyone with editor rights can add
a direct node or credential at any time; Veefore finds it on the next
verification, it does not prevent it. That is why a customer-owned instance is
reported **Partial** at best, never **Enforced within scope**. If you need
prevention, use the managed profile.
:::

## Requirements

- n8n 1.x or 2.x with the public API enabled (verified on 2.43.7).
- An n8n API key with the read scopes `workflow:list`, `workflow:read`,
  `credential:list`, `user:list` and `securityAudit:generate`. Older n8n
  without scoped keys works with a full key, but use a dedicated user.
- The Veefore gateway reachable from n8n.

## Step by step

:::steps
:::step Create the agent the instance acts as
In the console, **Agents → New agent**. Grant it the capabilities its workflows
need and authorize the tools under **Tools**. Copy the private key and key ID
shown once.
:::
:::step Register the instance
**Integrations → n8n — customer-owned → Add**. Enter the instance URL, the
read-scoped API key and the agent. The key is sealed into the credential broker
and never shown again. The runtime starts **Pending** and **Unverified**.
:::
:::step Install the node
Once the node is on npm: **Settings → Community nodes → Install**
`n8n-nodes-veefore`, or `npm install n8n-nodes-veefore` in `~/.n8n/nodes`.

From source (before it is published, or to pin a build): in the Veefore
repository,
```bash
cd integrations/n8n-nodes-veefore
npm install --ignore-scripts && npm run build
mkdir -p ~/.n8n/custom/n8n-nodes-veefore
cp -R dist package.json ~/.n8n/custom/n8n-nodes-veefore/
```
and start n8n with `N8N_CUSTOM_EXTENSIONS=~/.n8n/custom`. In Docker, mount that
folder and set the variable. Restart n8n; the node appears as **Veefore** (n8n
names it `CUSTOM.veefore` when loaded this way).

On n8n Cloud, see [n8n Cloud](/build/n8n-cloud).
:::
:::step Add the credential
In n8n, **Credentials → New → Veefore Agent API**: gateway URL, agent ID, key
ID, private key and the runtime connection ID from the runtime page. **Test**
signs an assertion and exchanges it for a session token, so a green test means
the gateway accepted the identity.
:::
:::step Replace direct actions
Use the **Veefore** node with **Execute action** wherever a workflow sends
mail, writes to a CRM, changes a database or calls a payment API. For AI agents,
connect the Veefore node as a **tool** instead of the provider's tool node.
Then delete the provider credentials from n8n.
:::
:::step Verify
On the runtime page, **Verify now**. Findings list each node and credential that
acts outside Veefore with the fix. Verification re-runs every
`RUNTIME_VERIFY_INTERVAL_SECONDS`, and a changed workflow is re-verified within
two minutes.
:::
:::

## The node

| Operation | What it does |
| --- | --- |
| Execute action | Runs the request through the full pipeline. A refusal fails the step (or returns the decision, with **Fail on refusal** off). |
| Authorize | Dry run. ALLOW returns an authorization bound to these exact parameters, valid 120 s, usable once. |
| Get approval status | Reads an approval this agent opened. |
| List permitted tools | The tools this agent may attempt. |

Every request carries the workflow ID, execution ID and node name, recorded in
the audit trail. The default idempotency key is `execution:node:item`, so a
retried step cannot act twice. With **Wait for approval** set, the node waits
for a person and then runs the approved action under its own key.

:::security Authorizing is not executing
"Authorize with Veefore, then send with the Gmail node" leaves the send
unmediated: nothing binds what Gmail sends to what was authorized. The verifier
flags this pattern as `VEEFORE_NODE_MISCONFIGURED`.
:::

## Fail closed (optional)

On the runtime's **Settings**, **Fail closed** makes the gateway refuse the
agent's protected actions while the runtime is **At risk** or **Unverified**,
and refuse any action from a workflow Veefore has not verified unchanged. A
bypass found in one workflow then stops the agent everywhere until it is fixed
or the risk is accepted. Turning it off later needs `runtime:operate` and
step-up.

## Upgrading

Upgrade the node with **Settings → Community nodes → Update**, or
`npm install n8n-nodes-veefore@latest`, then restart. The wire protocol is
versioned; the gateway accepts older node versions.

## Troubleshooting

| Symptom | Cause |
| --- | --- |
| Credential test: `AGENT_AUTHENTICATION_FAILED` | Wrong key ID or private key, or the gateway URL differs from the gateway's configured public URL (it is part of the signature). |
| `RUNTIME_MISMATCH` | The credential's runtime connection ID belongs to a different runtime than the agent's. |
| `RUNTIME_ENFORCEMENT_FAILED` | Fail closed is on and the runtime is At risk, Unverified, paused, or the workflow is unverified. |
| Verification: `n8n rejected the API key (401)` | The key was revoked or rotated in n8n; replace it on the runtime's Settings. |
| Verification: missing scope | Add the scope named in the error to the key. |
| The node does not appear | Restart n8n after installing; with `NODES_INCLUDE` set, add `CUSTOM.veefore` or `n8n-nodes-veefore.veefore`. |

## Related

:::cards
:::card Enforcement status | /concepts/enforcement-status
What each status means and how it is computed.
:::
:::card Bypass prevention | /secure/bypass-prevention
Every bypass scenario, what Veefore does, and what remains.
:::
:::card Veefore-managed n8n | /operate/managed-n8n
The profile that prevents rather than detects.
:::
:::