Access policy reference

The accessPolicy object controls which outbound HTTP requests each agent in your team is allowed to make. Policies are declared per-agent inside the team definition and travel with the team to any platform.

Where it lives

Access policies are declared inside the agents array of the team definition, directly on each agent object:

{
  "agents": [
    {
      "key": "coordinator",
      "name": "Triage Coordinator",
      "accessPolicy": {
        "default": "deny",
        "rules": [
          {
            "host": "api.zendesk.com",
            "methods": ["GET", "POST"],
            "effect": "allow"
          }
        ]
      }
    }
  ]
}

Each agent can have its own policy, or no policy at all. Agents without a policy are unrestricted — they may call any host.

Schema

accessPolicy object

Rule object

Evaluation

Rules are evaluated in order. The first matching rule wins. If no rule matches, default applies.

A request matches a rule when:

1. The host matches exactly
2. The request method is in methods (or methods is omitted)
3. The request path starts with any entry in paths (or paths is omitted)

Blocked requests return a structured error to the agent — the agent sees the refusal but the HTTP request is never sent.

Examples

Read-only access to a single host

The agent may only make GET requests to api.zendesk.com. All other outbound requests are blocked.

{
  "accessPolicy": {
    "default": "deny",
    "rules": [
      {
        "host": "api.zendesk.com",
        "methods": ["GET"],
        "effect": "allow"
      }
    ]
  }
}

Allowlist — multiple hosts

Allow two specific hosts, deny everything else.

{
  "accessPolicy": {
    "default": "deny",
    "rules": [
      {
        "host": "api.github.com",
        "effect": "allow"
      },
      {
        "host": "api.linear.app",
        "effect": "allow"
      }
    ]
  }
}

Block a specific path, allow the rest

Allow all requests to a host except the delete endpoint.

{
  "accessPolicy": {
    "default": "allow",
    "rules": [
      {
        "host": "api.zendesk.com",
        "methods": ["DELETE"],
        "paths": ["/v2/tickets"],
        "effect": "deny"
      }
    ]
  }
}

Allow all — explicit open policy

An agent that should be unrestricted but make the policy visible to deployers.

{
  "accessPolicy": {
    "default": "allow",
    "rules": []
  }
}

Setting the policy via API

Include accessPolicy in the definition.agents object when creating or updating a team:

POST /templates

{
  "slug": "support-triage",
  "definition": {
    "agents": [
      {
        "key": "coordinator",
        "name": "Coordinator",
        "accessPolicy": {
          "default": "deny",
          "rules": [
            { "host": "api.zendesk.com", "methods": ["GET", "POST"], "effect": "allow" }
          ]
        }
      }
    ]
  }
}

To update an existing team's access policy, PATCH the draft with the updated definition:

PATCH /templates/:draftId

{
  "definition": {
    "agents": [
      {
        "key": "coordinator",
        "accessPolicy": {
          "default": "deny",
          "rules": [
            { "host": "api.zendesk.com", "methods": ["GET", "POST", "PUT"], "effect": "allow" },
            { "host": "hooks.slack.com", "methods": ["POST"], "effect": "allow" }
          ]
        }
      }
    ]
  }
}

See the Building a team (API) guide for the full create/publish flow, and the full API reference for the complete schema.

Why declare a policy at all?

Deployers and their security teams inspect the access policy in the Library before installing your team. An explicit policy — even a permissive "default": "allow" — makes your team's network footprint auditable. Teams with no policy look opaque to security-conscious deployers and convert significantly worse.

Frequently asked questions

What happens if an agent tries to call a blocked host? The call is rejected and the run fails at that step. The error is logged in the observability dashboard with the agent key, the blocked URL, and the policy rule that rejected it — so you can audit exactly what each agent in your multi-agent workflow attempted.

Do I need to set an access policy on every agent? No — the default is no policy (unconstrained access). Setting a policy is recommended for any agent that handles sensitive data or makes external API calls. Agents without a policy look opaque to security-conscious deployers.

Can I set a policy that blocks all external calls? Yes — set "default": "deny" with an empty rules array. The agent will be unable to make any outbound HTTP calls. Use this for pure reasoning agents that should only process data passed to them internally.

Are access policies enforced by Envelope or by the runtime? Policies travel with the spec and are enforced by the runtime at deploy time. Envelope's hosted runtime enforces them natively. For self-hosted runtimes, check your adapter's documentation for enforcement support.

→ Credentials, trust and the AI operator problem — the broader trust model behind access policies and credential handling