> For the complete documentation index, see [llms.txt](https://docs.metamynd.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.metamynd.ai/the-architecture/the-governed-agent-gateway.md).

# The Governed Agent Gateway

The agent can ask; only the gateway can act. How the gateway holds the credentials and re-verifies every request before anything runs.

#### **The agent can ask. Only the gateway can act.**

An AI agent is untrusted by default — not because it's assumed malicious, but because it may be compromised, misconfigured, or simply wrong, and the architecture shouldn't depend on it being none of those things. The agent signs a request describing what it wants to do. It never holds the real upstream credential — the payment method, the booking-system API key, the database write permission — that would let it act directly. Only after the gateway independently verifies the request, and the issuer grants it a single-use claim, does the gateway attach the real credential and forward the call.

```mermaid
sequenceDiagram
    participant Agent as AI Agent<br/>(untrusted)
    participant GW as AgentSafe Gateway<br/>(enforcement point, own DID)
    participant MM as MetaMynd<br/>(policy + authorization)
    participant API as Real API<br/>(payment / booking / action)

    Agent->>MM: authorize (signed: agentDid|action|amount|… + payload digest)
    MM-->>Agent: allow + authorizationId (a hold)
    Agent->>GW: signed request + authorizationId + payload
    GW->>GW: ① Verify — signed, fresh, well-formed, allowed on this route
    GW->>MM: ② Re-check policy — fetch signed bundle (pinned key)
    GW->>MM: ③ Claim the hold (effect/dispatching, signed MAGP-SERVICE-v1, payload digest)
    MM-->>GW: grant (the hold's bound values) — or 409 already claimed / 403 digest mismatch
    GW->>API: Forward call, real credential attached, Idempotency-Key = authorizationId
    API-->>GW: Result
    GW->>MM: ④ Settle — capture / release / unknown
    GW-->>Agent: Result (never the credential itself)
```

*The agent proposes, AgentSafe verifies, the issuer grants exactly one claim, and only then does the action run. A failed check at any gateway step blocks the call before it reaches the real API.*

#### The gateway steps

1. **Verify** — signed, fresh, well-formed, allowed on this route. This mirrors step 5 (signature) and step 8 (freshness) of the [16 ordered checks](https://docs.metamynd.ai/agent-protocol/the-authorize-gate-16-ordered-checks).
2. **Re-check policy** — the gateway fetches the agent's signed policy bundle from `GET /policy/bundle/:did`, verifies it against the pinned policy key, and re-evaluates the request against it. It also compares the body it will forward with the payload the agent signed. That local comparison is a cheap early refusal — an **optimisation**, not the authority (see step 3).
3. **Claim the authorization** — the gateway claims the hold at the issuer with `POST /policy/mandate/authorize/:id/effect/dispatching`. The claim is atomic and single-use: of any number of claimants exactly one wins, and every other claim — a replay, a duplicate executor — gets `409 AUTHORIZATION_ALREADY_CLAIMED`. The gateway sends a fresh `Idempotency-Key` so a claim whose response was lost can be safely retried once. The `authorizationId` itself comes from the agent's authorize verdict; the claim returns a **grant** carrying the hold's bound values (and, for an anonymous claim, a claim token).

   **The authoritative payload check happens here.** The gateway states the digest of what it is about to execute (`x-magp-payload-digest`), and the issuer compares it with the digest it **stored** when it authorized the hold. A different digest is refused (`PAYLOAD_DIGEST_MISMATCH`) and the hold stays unclaimed. This matters because an agent that signs whatever it likes could hand a gateway a freshly signed request — new nonce, different digest — for the same authorization id; only the issuer knows which digest the authorization was actually granted for. This is what refuses the "sign cheap, ship expensive" class of attack: an agent can't get a $10 authorization and have the gateway execute a $1,000 one. See [Payload Binding](https://docs.metamynd.ai/core-concepts/payload-binding).
4. **Settle** — once the upstream answers, the gateway closes the hold: **capture** on success (with `payTo` and the settlement transaction for an x402 payment), **release** only when the upstream provably did not execute, and **unknown** for a timeout or ambiguous response, which hands the hold to reconciliation. See [Settlement & Settlement Evidence](https://docs.metamynd.ai/agent-protocol/settlement-and-settlement-evidence).

#### The gateway has its own identity

The gateway signs its claim and every settlement call with its own `did:key` or `did:hedera` (`MAGP-SERVICE-v1`, see [Request Signing](https://docs.metamynd.ai/agent-protocol/request-signing-and-message-format#service-counterparty-signature)). That identity is recorded as the claimer, and only it can later settle the hold lower or release it. For **mainnet** agents the gateway must also be in the owner's **trusted counterparty registry** — an unregistered service cannot claim at all. The hosted gateway scaffolded by `create-metamynd-agent` mints its own `did:key` and registers itself for you. See [Trusted Counterparties & Payee Directory](https://docs.metamynd.ai/core-concepts/trusted-counterparties-and-payee-directory).

#### Where the real credential comes from

The gateway holds the upstream credential, or obtains it **just in time** from the [Credential Vault](https://docs.metamynd.ai/verifai-trust-layer/credential-vault). The vault stores upstream credentials encrypted at rest and releases one only through `POST /credential-vault/resolve`, which requires both a gateway-only token (a secret the agent never holds) **and** a currently active [Action Passport](https://docs.metamynd.ai/verifai-trust-layer/action-passport) for that authorization. Every access is audited. `@metamynd/agentsafe-http-gateway` supports the vault as an optional hook; a gateway that keeps its own secrets locally is still supported.

#### Why the credential separation is the whole design

The single most consequential decision in this architecture is that the agent never touches the real credential. If an agent is compromised, jailbroken, or simply hallucinates an instruction, the worst it can do is sign a request — not execute an action. The gateway is the only component with the authority, and it makes that authority conditional on every step passing, every time, with no exceptions for "trusted" agents.

This also means governance isn't a courtesy the agent chooses to respect. A misbehaving or manipulated agent can't opt out of policy, because it was never in possession of anything policy could be bypassed to reach. The `create-metamynd-agent` scaffold makes this concrete. Its default hosted flow provisions a **testnet** agent (mainnet agents are launched from the dashboard [Launchpad](https://metamynd.ai/dashboard/launchpad) once the owner is verified) and generates **two separate processes**: the agent, which holds no real credentials, and a `gateway/` process that holds them, independently re-verifies every request, claims single-use authorizations and requires payload binding. `--no-gateway` scaffolds the old single-process example instead, and `--harness` builds a free, fully local harness with no network at all (add `--gateway` for a second local process) — both say plainly that they are not a separate enforcement boundary.

Keys get the same treatment: the agent's signing key can be held by the [`agentsafe-signer`](https://docs.metamynd.ai/sdks/agentsafe-signer) daemon (`keyProvider: 'daemon'`), so it never enters the agent's process at all. See [Key Custody & the Signer Daemon](https://docs.metamynd.ai/verifai-trust-layer/key-custody-and-the-signer-daemon).

#### Trustless re-verification at the edge

A conformant service doesn't take the caller's word that policy was checked. It resolves the agent's DID, fetches the current signed policy bundle, verifies it against the pinned policy key, and re-evaluates the request itself — the same way a browser verifies a certificate itself rather than asking the certificate authority on every page load. See [agentsafe-mcp-guard](https://docs.metamynd.ai/sdks/agentsafe-mcp-guard-service-side) and [Policy Bundle Pinning & Freshness](https://docs.metamynd.ai/agent-protocol/policy-bundle-pinning-and-freshness).

What local re-verification can decide on its own is a refusal, an escalation, or a non-value read. A **value-bearing** action also needs the stateful checks — replay, rate limits, circuit breakers, the cumulative-spend cap and the atomic reservation — which live at the gate. That is why the gateway claims the hold (`requireAuthorization: true` in the guard libraries) before it acts: if MetaMynd is unreachable, a value-bearing call is refused, not permitted. Bound capabilities can additionally be verified offline against `GET /magp/capability/pubkey`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.metamynd.ai/the-architecture/the-governed-agent-gateway.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
