Policy Rules: Organization-Wide Guardrails

Policy rules are your organization’s guardrails. They apply across every project and every agent: block operations, require human approval, or cap usage, all in one ordered list your whole team can read. Per-agent access within a project is managed with agent grants — rules are the level above, and no grant can loosen them.

Why rules matter

Credentials get an agent through the door. Rules decide what it can do once inside. Without guardrails, an agent granted Gmail can read, send, and delete emails with no limit. That’s useful, but it’s also how you get an agent mass-deleting an inbox before anyone can stop it. Rules let you say things like “in this organization, deleting repositories is never allowed” — once, for everyone.

Deterministic enforcement, not prompts

You can tell an agent “never delete emails without my approval” in a system prompt. But a prompt is a suggestion, not a guarantee. Agents are non-deterministic. They can be manipulated through prompt injection, they can misinterpret instructions, or they can be too eager to please and take actions you didn’t intend. Rules are different. They’re enforced outside the agent, at the gateway level, before the request ever reaches the external service. If a rule blocks Gmail deletes, that request is blocked. Every time, deterministically, regardless of what the agent was told or tricked into doing.

How the policy engine works

Every request an agent makes passes through the gateway, which evaluates rules top-down, first match wins:

Organization rules run first: org-wide guardrails an individual project cannot loosen. This is the level you author on this page.
Project-level access runs next — compiled automatically from each agent’s grants. You never author project rules directly; attaching a connection or secret writes them for you.
Each level ends in a Default Rule, which decides what happens when nothing matched (Allow or Block).

A request is allowed only when both levels permit it. The first rule whose identities and targets match decides; later rules never run, so order matters (drag rules in the console, or reorder via the API).

Rules vs grants

	Organization rules	Agent grants
Scope	Every project and agent	One agent, one credential
Direction	Ceiling — can only restrict	Grant — provides access
Authored	Policy console / `onecli org policy`	Agent pages / `onecli agents grants`
Takes effect	On publish (staged draft)	Immediately
Identities	Users, user groups, or everyone	The one agent

Draft and publish

Organization rule edits never take effect immediately. Changes stage into a draft; the gateway keeps enforcing the last published set until you click Apply Changes (or call the publish API). Publishing snapshots the entire draft (including changes staged by teammates), so review the pending list before applying.

The Policy console: an ordered rule list evaluated top-down

Anatomy of a rule

A rule pairs who (identities) with what (targets), and applies an action with optional modifiers.

Identities: who the rule applies to — specific users or user groups. Empty means everyone in the organization.
Targets: at least one destination:
- an app ({"kind":"app","provider":"gmail","tools":["send_email"]}), optionally narrowed to specific catalog tools, or the whole app when tools is omitted;
- a connection ({"kind":"connection","connectionId":"..."}): one specific connected account;
- a secret ({"kind":"secret","secretId":"..."}): a stored credential and its host;
- a network pattern ({"kind":"network","hostPattern":"api.example.com","pathPattern":"/v1/*","method":"POST"}).
Action: allow or block.
Modifiers (allow rules only): requireApproval holds matching requests for a human decision; rateLimit plus rateLimitWindow cap usage, with each agent tracking its own counter.

Authoring a rule: name, action, targets, and modifiers

Creating rules

Organization rules require an organization API key (oc_org_…) with the admin role. From the console: Policy → Add Rule. From the CLI:

onecli org policy rules create \
  --name "Gmail sends need approval" \
  --action allow \
  --targets '[{"kind":"app","provider":"gmail","tools":["send_email"]}]' \
  --require-approval

{
  "rule": {
    "id": "9f2c1b8a",
    "scope": "organization",
    "status": "draft",
    "generation": 0,
    "priority": 3,
    "enabled": true,
    "isDefault": false,
    "logicalId": "b41a77c2",
    "source": "custom",
    "name": "Gmail sends need approval",
    "description": null,
    "action": "allow",
    "rateLimit": null,
    "rateLimitWindow": null,
    "requireApproval": true,
    "identities": [],
    "targets": [{ "kind": "app", "provider": "gmail", "tools": ["send_email"] }],
    "createdAt": "2026-07-21T09:15:00.000Z"
  },
  "published": true,
  "generation": 7
}

CLI writes auto-publish when the draft has no other staged changes; otherwise the publish is withheld (publishSkipped appears in the output) so you never accidentally ship a teammate’s half-finished edits. Review with onecli org policy status, then onecli org policy publish, or pass --publish-all. Use --no-publish to stage deliberately. The same rule via the API (organization scope — no X-Project-Id):

curl -X POST https://api.onecli.sh/v1/org/policy/rules \
  -H "Authorization: Bearer $ONECLI_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gmail sends need approval",
    "action": "allow",
    "requireApproval": true,
    "targets": [{"kind":"app","provider":"gmail","tools":["send_email"]}]
  }'

Then make it enforce with POST /v1/org/policy/publish, or Apply Changes in the console. Read the enforced set with GET /v1/org/policy/rules?status=published, and compare draft against published rules by logicalId (published row ids regenerate on every publish).

Examples

Block a destructive operation everywhere (applies to every project and agent):

onecli org policy rules create \
  --name "Never delete repos" \
  --action block \
  --targets '[{"kind":"network","hostPattern":"api.github.com","pathPattern":"/repos/*","method":"DELETE"}]'

{
  "rule": {
    "id": "c81f3a20",
    "scope": "organization",
    "status": "draft",
    "generation": 0,
    "priority": 0,
    "enabled": true,
    "isDefault": false,
    "logicalId": "e63d09b7",
    "source": "custom",
    "name": "Never delete repos",
    "description": null,
    "action": "block",
    "rateLimit": null,
    "rateLimitWindow": null,
    "requireApproval": false,
    "identities": [],
    "targets": [
      {
        "kind": "network",
        "hostPattern": "api.github.com",
        "pathPattern": "/repos/*",
        "method": "DELETE"
      }
    ],
    "createdAt": "2026-07-21T09:20:00.000Z"
  },
  "published": true,
  "generation": 3
}

Cap an expensive API (allow plus a rate limit; each agent gets its own counter):

onecli org policy rules create \
  --name "Limit Anthropic calls" \
  --action allow \
  --targets '[{"kind":"network","hostPattern":"api.anthropic.com"}]' \
  --rate-limit 100 --rate-limit-window hour

{
  "rule": {
    "id": "1d40b7ce",
    "scope": "organization",
    "status": "draft",
    "generation": 0,
    "priority": 4,
    "enabled": true,
    "isDefault": false,
    "logicalId": "a90c55f1",
    "source": "custom",
    "name": "Limit Anthropic calls",
    "description": null,
    "action": "allow",
    "rateLimit": 100,
    "rateLimitWindow": "hour",
    "requireApproval": false,
    "identities": [],
    "targets": [{ "kind": "network", "hostPattern": "api.anthropic.com" }],
    "createdAt": "2026-07-21T09:22:00.000Z"
  },
  "published": true,
  "generation": 8
}

Scope one agent’s access — that’s a grant, not a rule. To give an agent read-only Gmail, attach the connection with only the read tools allowed:

onecli agents grants attach-connection --id agent_abc123 --connection-id conn_9f2c1b \
  --allow read_all

See Agent access for the full grant model. Discover an app’s tool ids (including group wildcards like read_all and write_all where the app supports them). Output abridged to a few tools per group; the real catalog lists every tool:

onecli apps permission-definition --provider gmail --fields groups

{
  "groups": [
    {
      "category": "read",
      "tools": [
        { "id": "search_messages", "name": "Search messages", "description": "Search and list messages matching a query" },
        { "id": "get_message", "name": "Read message", "description": "Retrieve a specific email message" }
      ],
      "wildcard": {
        "id": "read_all",
        "name": "All read operations",
        "description": "Search, read, and list emails, threads, drafts, labels, and settings"
      }
    },
    {
      "category": "write",
      "tools": [
        { "id": "send_email", "name": "Send email", "description": "Send email on your behalf" }
      ],
      "wildcard": {
        "id": "write_all",
        "name": "All write operations",
        "description": "Send, import, create drafts, modify labels, trash, and delete emails and threads"
      }
    }
  ]
}

Conditions

Conditions narrow a rule beyond its targets by inspecting the request body. Each condition names a target (body), an operator (contains), a value, and an optional key to scope the match to one JSON field; multiple conditions are ANDed.

onecli org policy rules create \
  --name "Approve large charges" \
  --action allow --require-approval \
  --targets '[{"kind":"network","hostPattern":"api.stripe.com","pathPattern":"/v1/charges","method":"POST"}]' \
  --conditions '[{"target":"body","operator":"contains","value":"10000","key":"amount"}]'

{
  "rule": {
    "id": "5e8c02af",
    "scope": "organization",
    "status": "draft",
    "generation": 0,
    "priority": 6,
    "enabled": true,
    "isDefault": false,
    "logicalId": "d24f18e0",
    "source": "custom",
    "name": "Approve large charges",
    "description": null,
    "action": "allow",
    "rateLimit": null,
    "rateLimitWindow": null,
    "requireApproval": true,
    "conditions": [
      { "target": "body", "operator": "contains", "value": "10000", "key": "amount" }
    ],
    "identities": [],
    "targets": [
      {
        "kind": "network",
        "hostPattern": "api.stripe.com",
        "pathPattern": "/v1/charges",
        "method": "POST"
      }
    ],
    "createdAt": "2026-07-21T09:26:00.000Z"
  },
  "published": true,
  "generation": 10
}

Allow rules with a single specific connection target instead accept a session policy object for resource scoping: {"repositories": ["org/repo"]} (GitHub) or {"folders": ["/exports"]} (file providers), restricting which resources that connection can touch.

Manual approval

An allow rule with requireApproval holds matching requests until a human decides — the same mechanism the Ask state in a per-tool grant uses. The gateway keeps the agent’s connection open (up to 5 minutes) while it waits; unanswered requests are denied. The reviewer sees the method and URL, sanitized headers, and a body preview, so they can judge exactly what the agent is trying to do. Decisions flow through the console, or programmatically via the SDK:

const handle = onecli.configureManualApproval(async (request) => {
  console.log(`${request.method} ${request.url}`);
  return "approve"; // or "deny"
});

See the Node SDK reference for the org-wide variant.

App permissions and the ceiling

The per-app App Permissions panel at the organization level writes ordinary policy rules with an app target — per-tool guardrails like “GitHub pushes need approval”, exactly like the examples above. Whatever the organization sets is a ceiling for every project: a grant can allow a tool for an agent, but if an organization rule blocks it or requires approval, the strictest answer wins. In the project’s per-tool dialog those rows show as locked. Read the effective per-tool state:

# The organization level alone (admin, org key)
curl "https://api.onecli.sh/v1/org/policy/effective-app-permissions?provider=gmail" \
  -H "Authorization: Bearer $ONECLI_ORG_API_KEY"

# One project's enforced result (grants + organization rules combined)
curl "https://api.onecli.sh/v1/policy/effective-app-permissions?provider=gmail" \
  -H "Authorization: Bearer $ONECLI_API_KEY" \
  -H "X-Project-Id: $PROJECT_ID"

Each tool in the project view carries an orgCeiling field — what the organization level alone would decide, independent of any grant.

How rules interact with credentials

Rules evaluate before credential injection. A blocked request is rejected at the gateway: the credential is never attached, and the upstream service never sees the request. Which credential is injected is decided by the agent’s grants.

Availability

The organization policy console and /v1/org/policy/* API are available on OneCLI Cloud and self-hosted Enterprise. On Community (OSS) and single-project deployments there is no organization level: agent grants are the whole policy surface — per-agent, per-tool access without a rules console on top. The retired project-scope authoring surface (/v1/policy/rules writes, /v1/rules/*, /v1/org/rules/*) returns 410 Gone on current servers, pointing at grants (project access) or this page’s API (organization rules). See API errors for the full retirement inventory.

Coming soon

Monitor action: log matching requests without blocking, useful for auditing before enforcing
Time-bound access: grant access only during specific time windows

​Why rules matter

​Deterministic enforcement, not prompts

​How the policy engine works

​Rules vs grants

​Draft and publish

​Anatomy of a rule

​Creating rules

​Examples

​Conditions

​Manual approval

​App permissions and the ceiling

​How rules interact with credentials

​Availability

​Coming soon