Documentation

Action Gateway

Verify checks whether an action is allowed. The Action Gateway enforces that decision by executing only supported allowed actions through BehalfID.

MVP scope

The current gateway supports one safe executor: public web reads. It accepts browse_web on the web resource, fetches a public URL with GET, and returns a status, content type, optional title, and limited text excerpt.

The gateway does not submit forms, log in, purchase items, send email, write calendars, run arbitrary browser automation, forward arbitrary headers, or use credentials or cookies.

Fail closed

Passports define permissions. Verify checks those permissions. The gateway adds an execution boundary: denied or unsupported actions return executed: false, and BehalfID does not fetch or perform anything after denial.

The gateway verifies before any executor runs. A denied decision, approval-required permission, missing constrained input, unsupported action, or verification failure stops the flow before the public-web-read fetch is attempted.

{
  "agentId": "agent_xxx",
  "action": "browse_web",
  "resource": "web",
  "input": {
    "url": "https://example.com"
  }
}

curl -X POST "$BASE_URL/api/actions/execute" \
  -H "Authorization: Bearer $BEHALFID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"agent_xxx","action":"browse_web","resource":"web","input":{"url":"https://example.com"}}'

Runnable demo

The examples/enforcement-demo package runs this flow against a real agent. It creates permissions, runs an allowed web read through the Action Gateway, proves denied executors do not run, and checks that the request IDs are present in the audit logs.

cd examples/enforcement-demo
npm install
cp .env.example .env
npm run setup
npm run demo

Security controls

• Only GET is used.
• No cookies, credentials, or user-supplied request headers are sent.
• Only http:// and https:// URLs are accepted.
• Localhost, private IP ranges, link-local addresses, metadata IPs, and internal hostnames are blocked.
• Redirects are followed manually and each target is validated before another fetch occurs.
• Requests have a timeout and response bodies are capped before excerpts are returned.

Later connectors

Future connectors can add more actions, but each connector needs its own narrow executor, permission check, input validation, and fail-closed behavior.