> ## Documentation Index
> Fetch the complete documentation index at: https://mandatez.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# MandateZ Proxy Mode — Zero-Code Governance
> Point your agent's HTTP client at the MandateZ proxy and every outbound API call is policy-checked, signed, and logged — no SDK install required.
# MandateZ Proxy Mode — Zero-Code Governance
Proxy Mode is the fastest path to MandateZ governance. Instead of installing `@mandatez/sdk`
and refactoring your agent's action layer, you repoint your HTTP client at the MandateZ proxy
and every outbound call to OpenAI, Anthropic, Stripe, Supabase, Slack, or any other API is:
* **Policy-checked** against the rules you've configured in your dashboard
* **Signed** with an Ed25519 key escrowed by MandateZ and bound to your agent ID
* **Logged** to the same `agent_events` stream the SDK writes to
* **Trust-scored** in the background
No code changes to your agent. No private key to manage. Adoption without decision.
Proxy Mode is the right first integration when you need governance working in under ten
minutes or when you cannot modify the agent's source (third-party SaaS, compiled binaries,
n8n nodes). For full SDK capabilities — per-agent keypairs you control, synchronous
oversight gates with `waitForApproval`, cross-agent verification — use the SDK directly.
## How It Works
```
Your Agent → MandateZ Proxy → Target API (OpenAI, Anthropic, Stripe, …)
↓
Policy check
Signed event log
Trust score update
Oversight alert on flagged action
```
Your agent makes its outbound request to `https://core-dashboard-black.vercel.app/api/proxy`
instead of directly to the target API. The proxy reads three `X-MandateZ-*` headers, evaluates
the call against your configured policies, and — if allowed — forwards the request to the real
target. The target's response is relayed back unchanged. If the call is blocked, the target
API is never contacted and your agent receives a 403 with the policy reason.
## Setup — Three Steps
### Step 1 — Configure Your HTTP Client
Prefix your existing API calls with the MandateZ proxy URL and add three headers. Everything
else (auth headers, body, method) stays identical to the direct call.
#### Python
```python theme={null}
import httpx
import os
client = httpx.Client(
base_url="https://core-dashboard-black.vercel.app/api/proxy",
headers={
"X-MandateZ-Agent-ID": "ag_your_agent_id",
"X-MandateZ-Owner-ID": "your_owner_id",
},
timeout=30.0,
)
response = client.post(
"/",
headers={
"X-MandateZ-Target-URL": "https://api.openai.com/v1/chat/completions",
"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}",
"Content-Type": "application/json",
},
json={
"model": "gpt-4",
"messages": [{"role": "user", "content": "Hello"}],
},
)
if response.status_code == 403:
# Blocked by policy — response.json() has policy_id and reason
raise RuntimeError(response.json())
```
#### Node.js
```typescript theme={null}
const response = await fetch(
'https://core-dashboard-black.vercel.app/api/proxy',
{
method: 'POST',
headers: {
'X-MandateZ-Agent-ID': 'ag_your_agent_id',
'X-MandateZ-Owner-ID': 'your_owner_id',
'X-MandateZ-Target-URL': 'https://api.openai.com/v1/chat/completions',
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
},
body: JSON.stringify({
model: 'gpt-4',
messages: [{ role: 'user', content: 'Hello' }],
}),
}
);
if (response.status === 403) {
const { policy_id, reason } = await response.json();
throw new Error(`Blocked by ${policy_id}: ${reason}`);
}
const data = await response.json();
```
### Step 2 — Set Policies in Your Dashboard
Define which action types (`read`, `write`, `export`, `delete`, `call`, `payment`) and resource
patterns the agent is allowed to hit. The proxy evaluates every forwarded call against these
rules before contacting the target.
Example policy covering the Vercel-class failure mode:
```json theme={null}
{
"id": "pol_proxy_default",
"name": "Production Default",
"rules": [
{ "id": "r1", "action_types": ["call"], "resource_pattern": "openai/v1/chat/completions", "effect": "allow" },
{ "id": "r2", "action_types": ["call"], "resource_pattern": "anthropic/v1/messages", "effect": "allow" },
{ "id": "r3", "action_types": ["*"], "resource_pattern": "stripe/v1/*", "effect": "flag" },
{ "id": "r4", "action_types": ["*"], "resource_pattern": "supabase/rest/*/env/*", "effect": "block" },
{ "id": "r5", "action_types": ["*"], "resource_pattern": "*", "effect": "block" }
]
}
```
### Step 3 — Watch Events Stream in Real Time
Every proxied call produces a signed `AgentEvent` visible in the live event feed. The event
records the action type, derived resource, outcome, policy ID, HTTP method, status code, and
latency — but never the request or response body.
## Request Headers Reference
| Header | Required | Description |
| ------------------------ | -------- | --------------------------------------------------------------------------------------- |
| `X-MandateZ-Agent-ID` | ✓ | The agent ID (e.g. `ag_xK9mP2...`). First call auto-provisions an escrowed signing key. |
| `X-MandateZ-Owner-ID` | ✓ | Your organization's owner ID. Must match the agent's registered owner. |
| `X-MandateZ-Target-URL` | ✓ | The real URL the proxy should forward the request to. |
| `X-MandateZ-Action-Type` | — | One of `read`, `write`, `export`, `delete`, `call`, `payment`. Defaults to `call`. |
| `X-MandateZ-Resource` | — | Override the auto-derived resource string. Useful for custom hosts. |
All other headers (including `Authorization` and `Content-Type`) pass through to the target
unchanged. MandateZ strips `X-MandateZ-*` headers before forwarding so the target API never
sees them.
## Response Headers
On successful proxy, the response includes:
| Header | Description |
| ---------------------- | -------------------------------------- |
| `X-MandateZ-Agent-ID` | The agent ID the call was signed under |
| `X-MandateZ-Resource` | The derived resource string |
| `X-MandateZ-Outcome` | `allowed` or `flagged` |
| `X-MandateZ-Policy-Id` | The policy that matched (if any) |
## What Gets Governed
The proxy automatically maps each target URL to a resource string your policies can match.
Well-known hosts fold into a short prefix; custom hosts fall back to the full hostname.
| API | Auto-mapped resource pattern |
| ------------- | ---------------------------- |
| OpenAI | `openai/v1/*` |
| Anthropic | `anthropic/v1/*` |
| Stripe | `stripe/v1/*` |
| Supabase | `supabase/*` |
| Slack | `slack/*` |
| GitHub | `github/*` |
| Twilio | `twilio/*` |
| SendGrid | `sendgrid/*` |
| Resend | `resend/*` |
| Vercel | `vercel/*` |
| Custom domain | `your-domain.com/*` |
You can override the auto-derived resource with the `X-MandateZ-Resource` header — useful when
you want to group multiple upstream APIs under a single policy prefix.
## Privacy
MandateZ Proxy **does not store request or response bodies**. Only the action type, resource,
outcome, policy ID, HTTP method, status code, and timestamp are logged — never your prompts,
API payloads, or upstream responses.
Every event is Ed25519-signed by an escrowed key bound to your agent ID. Because the key is
managed by MandateZ on your behalf, Proxy Mode's audit trail is most useful when governance
is the security boundary. For workloads where cryptographic non-repudiation from the agent
runtime itself is required (e.g. EU AI Act Article 12 for regulated-industry deployments),
use the SDK directly so the private key never leaves your infrastructure.
## Network Policy
MandateZ Proxy forwards only to public HTTPS endpoints. Private IPs (RFC1918, loopback,
link-local, CGNAT), cloud metadata endpoints (`169.254.169.254`,
`metadata.google.internal`), and plain HTTP targets are rejected with a 400. Request bodies
larger than 5 MB are rejected with a 413.
## Cache Behaviour
Proxy Mode caches your per-owner policy list in memory for **30 seconds**. Policy changes
made through the dashboard take effect on the next cache refresh — worst case \~30 s for a
hot proxy instance, immediate for a cold one. If you need to force a policy rollout faster,
redeploy the dashboard or evict the cache entry for that owner.
## Proxy Mode vs SDK
| | Proxy Mode | SDK |
| ---------------------------------------------- | ------------------------------------- | ---------------------------- |
| Install step | None — point HTTP client at proxy URL | `npm install @mandatez/sdk` |
| Private key management | Escrowed by MandateZ | Managed by you |
| Policy enforcement | Yes — at the network edge | Yes — at the action boundary |
| Signed event log | Yes | Yes |
| Synchronous oversight gate (`waitForApproval`) | No — async alert only | Yes |
| Cross-agent verification | No | Yes (`verifyAgent`) |
| Works with third-party/SaaS agents | Yes | No |
| Added latency per call | \~30–80 ms | \~0 ms |
| Right first move when... | You want governance in 10 minutes | You want the full stack |
Proxy Mode and the SDK write to the same `agent_events` stream — you can switch between them
or run both on the same agent without losing audit continuity.
***
Open your dashboard, copy the Proxy Setup snippet, and route your first call through MandateZ in under 60 seconds.