Policies

A policy decides what happens when an action runs: allow, deny, or require approval. Policies are evaluated on direct action execution and on proxy calls — before anything reaches the provider.

What a policy matches

A policy in an environment has:

• provider_config_key — which provider (default * = all).
• action_pattern — which actions, e.g. *, send-*, list-repos (actions are matched in slash form, e.g. github/send-message).
• effect — allow, deny, require_approval, or transform.
• condition — an optional condition (DSL, or Rego with the OPA backend) so a rule applies only when the payload/context matches.
• transform — for the transform effect, which payload fields to sanitize before the action runs.
• enabled and audit_only — audit_only evaluates the rule and records what it would have done without actually enforcing it (a safe way to trial a policy).

How a decision is reached

When several policies match, the most restrictive wins: deny > require_approval > allow. An enforcing rule beats an audit_only shadow of the same rank.

The outcome:

• deny → the call returns 403 and never executes (an audit_only deny returns 200 but is recorded as a would-deny).
• require_approval → the call returns 202 with an approval_id; the action is held for approval.
• transform → the action runs against a sanitized payload (the listed fields are redacted); the response tells the agent exactly which fields were transformed. A field outside the payload fails closed.
• allow → the action executes.

For payload-level sanitization across all actions (not just one policy), see content-level data redaction, which also writes signed receipts.

Default-deny on writes

Actions are classified read, write, or destructive (from HTTP method + name — delete/remove/refund/… are destructive; create/update/send/charge/… are writes). With the environment flag POLICY_DEFAULT_DENY_WRITES (on by default — secure by default), any write or destructive action with no matching allow policy is denied, so an agent can only write where you've explicitly permitted it. Reads always default to allow. Set the flag to false only for an environment you intend to leave open.

Manage policies

Policies are managed under /api/v1/governance/policies (JWT auth; canManagePolicies).

Dry-run a check

POST /api/v1/actions/{provider}/{action_name}/policy-check

returns the disposition (allowed / approval / denied) and the matching policy without executing anything.