paybondpaybond
Sign in

Enterprise policy inheritance

Org-level base policies that tenants extend with overlays — shared spend rules across business units with tenant isolation.

Enterprise deployments can publish org base policies that tenant overlays extend. Each business unit keeps a local paybond.policy.yaml overlay while inheriting shared side-effecting tool definitions, evidence presets, and spend caps from the platform operator.

Tenant isolation remains absolute: overlays never merge policies from another org, and tenants cannot widen org allowed_tools or raise org spend caps.

Inheritance model

Org base policy (platform-published)
        +
Tenant overlay (paybond.policy.yaml)
        ↓
Effective policy (per tenant, Gateway-resolved)

Gateway resolves the merged effective policy so tenants cannot bypass org constraints by editing local files alone. Kit middleware consumes the effective policy the same way as a flat v1 policy file.

Schema v2

Org base policies use version: 2 without an extends block:

version: 2
name: acme-agent-spend-v1
default_deny: true

tools:
  travel.book_hotel:
    side_effecting: true
    max_spend_cents: 20000
    evidence_preset: cost_and_completion

intent:
  policy_binding:
    template_id: completion_budget_v1
  allowed_tools:
    - travel.book_hotel

Tenant overlays declare what they extend and what they override:

version: 2
name: acme-travel-tenant-east
extends:
  org_policy_id: acme-agent-spend-v1
  org_id: org_acme_corp

default_deny: true

overrides:
  tools:
    travel.book_hotel:
      max_spend_cents: 15000  # stricter than org default
  intent:
    budget:
      max_spend_usd: 150

tools:
  acme.internal.approve_po:
    side_effecting: true
    evidence_preset: cost_and_completion

Merge rules (deterministic):

FieldRule
toolsUnion; tenant wins on spend/evidence conflicts; cannot remove org-required side-effecting tools
default_denyTenant may only make stricter (true wins)
intent.allowed_toolsIntersection when org defines an allowlist; tenant may narrow, not widen
evidence_presetTenant may swap only within org-approved catalog subset

For offline CI, add extends.base_policy pointing at a checked-in org base file. Production should use Gateway effective resolution.

CLI workflow

Platform operator: scaffold org base

paybond policy init-org \
  --policy-id acme-agent-spend-v1 \
  --out org-agent-spend-v1.yaml \
  --operation travel.book_hotel \
  --evidence-preset cost_and_completion \
  --max-spend-cents 20000

Review the file, then publish via Gateway (requires platform operator credentials or PAYBOND_ORG_POLICY_PUBLISH_SECRET):

curl -X PUT \
  "https://api.paybond.ai/v1/admin/org-policies/acme-agent-spend-v1?org_id=org_acme_corp" \
  -H "Authorization: Bearer $PAYBOND_ORG_POLICY_PUBLISH_SECRET" \
  -H "Content-Type: application/json" \
  --data-binary @org-agent-spend-v1.json

See Gateway API — org policy inheritance.

Tenant: scaffold overlay

paybond policy extend \
  --extends org_acme_corp/acme-agent-spend-v1 \
  --out paybond.policy.yaml

Optional tenant-only tool:

paybond policy extend \
  --extends org_acme_corp/acme-agent-spend-v1 \
  --operation acme.internal.approve_po \
  --evidence-preset cost_and_completion \
  --out paybond.policy.yaml

For local merge in CI, pin the org base file:

paybond policy extend \
  --extends org_acme_corp/acme-agent-spend-v1 \
  --base-policy ./org-agent-spend-v1.yaml \
  --out paybond.policy.yaml

Validate merged policy (server)

paybond login
paybond policy validate-tools \
  --file paybond.policy.yaml \
  --remote \
  --resolve-inheritance \
  --format json

The response includes effective_policy_digest and merge_report when inheritance resolves successfully.

Kit API

TypeScript:

import { PaybondPolicy } from "@paybond/kit/policy";

const { policy, report, effectivePolicyDigest } = await PaybondPolicy.loadEffective({
  overlay: "./paybond.policy.yaml",
  gateway: paybond.harbor,
});
const registry = policy.toToolRegistry();

Offline merge (best-effort CI):

const { policy } = await PaybondPolicy.mergeLocal({
  base: "./org-agent-spend-v1.yaml",
  overlay: "./paybond.policy.yaml",
});

Python parity:

from paybond_kit.policy import PaybondPolicy, resolve_policy_effective_remote

result = await resolve_policy_effective_remote(overlay_doc, gateway_client)
policy = PaybondPolicy.from_document(result.effective_policy)

Examples

Repository examples under kit/policy/examples/:

  • org-base-acme-agent-spend-v1.json — org base
  • tenant-overlay-acme-travel-east.json — tenant overlay with overrides