> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Agent Approval plugin

> Reference for the Agent Approval plugin, which requires a human approval token before an agent can make matching requests.

The Agent Approval plugin requires a human approval token on requests that match its conditions, such as a method, a path, or an MCP tool. An agent sends the token in a header, or, on an MCP `tools/call`, in an `approval` parameter. Without a valid token, the request is refused. Only agents are asked unless `apply_to_humans` is on.

A caller is an agent when [JWT Auth](/reference/plugins/jwt-auth) identified it and its token marks it as an agent.

## Where it runs

|             |                                                                                                                                                                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Protocols   | The console offers it for MCP routes. The gateway itself runs it on any protocol, so a `global` instance also applies to HTTP and LLM routes. `require_for.mcp_tools` and the `approval` parameter apply to MCP `tools/call` only. |
| Scope kinds | `global`, `route`, on MCP routes                                                                                                                                                                                                   |
| Phase       | Request                                                                                                                                                                                                                            |

## Configuration

**`require_for.methods`** `array of strings`

Methods that need approval, in any letter case. The console labels this **Require methods**.

---

**`require_for.path_exact`** `array of strings`

Exact paths that need approval.

---

**`require_for.path_prefixes`** `array of strings`

Path prefixes that need approval. The console labels this **Require path prefixes**.

---

**`require_for.scopes`** `array of strings`

A caller holding any of these scopes needs approval. The console labels this **Require scopes**.

---

**`require_for.mcp_tools`** `array of strings`

MCP tool name patterns that need approval. A pattern ending in `*` matches by prefix, and one starting with `*` matches by suffix.

---

**`approval_header`** `string` — default: X-Agent-Approval

The header that carries the token.

---

**`validator`** `string` — default: static (on most data planes)

How to check the token. `static` checks it against `static_tokens`. A data plane set up with an identity service defaults to a different validator, so always set `validator` to `static` and fill in `static_tokens`. The console labels the blank option "default (iam)".

---

**`static_tokens`** `object`

Maps an approver name to `sha256:` followed by the full 64-character hexadecimal SHA-256 of that approver's secret. The gateway checks the stored value only as a prefix, so a shorter or empty value approves other secrets.

---

**`apply_to_humans`** `boolean` — default: false

Also asks users and callers with no agent identity for approval.

---

With no `require_for` condition, nothing needs approval. A request needs approval when any one condition holds.

With the `static` validator, the token has the form `<approver>:<secret>`. A missing token gets "human approval required", and an invalid one gets "approval token rejected". The token stays on the request and is forwarded to the upstream.

## Example

```json
{
  "name": "approve-deletes",
  "plugin_id": "agent-approval",
  "scope": { "kind": "route", "name": "linear-mcp" },
  "config": {
    "require_for": { "mcp_tools": ["delete_*"] },
    "validator": "static",
    "static_tokens": {
      "alice": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    }
  }
}
```

## Related guides

* [Authenticate requests with JWT Auth](/configure/authentication/jwt-auth)