# Access policy reference

URL: https://openenvelope.org/docs/access-policy

# 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:

```json
{
  "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

| Field | Type | Required | Description |
|---|---|---|---|
| `default` | `"allow"` \| `"deny"` | Yes | Action taken when no rule matches an outbound request |
| `rules` | `Rule[]` | Yes | Ordered list of rules evaluated against each request |

### Rule object

| Field | Type | Required | Description |
|---|---|---|---|
| `host` | `string` | Yes | Hostname to match, e.g. `"api.zendesk.com"`. No wildcards — exact hostname match only. |
| `methods` | `string[]` | No | HTTP methods to match. Accepted values: `"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"`, `"HEAD"`, `"OPTIONS"`. Omit to match all methods. |
| `paths` | `string[]` | No | Path prefix patterns to match, e.g. `["/v2/tickets"]`. Omit to match all paths under the host. |
| `effect` | `"allow"` \| `"deny"` | Yes | Whether to allow or block a request that matches this rule |

---

## 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.

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

### Allowlist — multiple hosts

Allow two specific hosts, deny everything else.

```json
{
  "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.

```json
{
  "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.

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

---

## Setting the policy via API

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

```
POST /templates
```

```json
{
  "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
```

```json
{
  "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)](/docs/builder-api) guide for the full create/publish flow, and the [full API reference](/api-docs#access-policy) 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](/writing/credentials-trust) — the broader trust model behind access policies and credential handling