Policies

A policy decides what happens to each tool call an agent makes: allow it, require approval for it, or deny it. Every agent points at one policy (an agent without one has every call denied), and the Gateway evaluates that policy's active version on every call.

A policy is a named container of versions. Each version is a JSON document of rules that never changes once saved. At most one version of a policy is active at a time; you change behaviour by saving a new version and activating it, and you can always go back to an earlier one.

The policy document

A policy version is a JSON document with three members:

{
  "schema": "kblock.cloud/policy@1",
  "default": "deny",
  "rules": [
    {
      "id": "small-refunds",
      "actions": ["refund.create"],
      "amount": { "currency": "USD", "lte": "100" },
      "effect": "allow"
    },
    {
      "id": "large-refunds",
      "actions": ["refund.create"],
      "amount": { "currency": "USD", "gt": "100" },
      "effect": "require_approval",
      "approvers": { "roles": ["owner", "admin"] },
      "approval_ttl_seconds": 3600
    },
    {
      "id": "no-exports",
      "actions": ["customer.export"],
      "effect": "deny"
    }
  ]
}

This example allows refunds up to 100 USD, sends larger refunds to an owner or admin for approval within an hour, denies customer exports, and denies everything else through its default. A refund without a USD amount also needs approval, because amount conditions fail closed (see below).

Rules

Unknown members are refused, and validation reports every problem at once with its location in the document. The rule language is covered in depth in Rules, amounts and currencies.

How a call is evaluated

For each call, the Gateway takes the call's action (from the tool's action mapping), the exposed tool name and the amount (from the tool's amount mapping), and evaluates the agent's active policy version:

1. Find candidates. A rule is a candidate when one of its actions patterns matches the call's action, its tools (if present) include the tool, and its amount condition (if present) holds.
2. Fail closed on amounts. If a rule has an amount condition and the call has no amount, or an amount in another currency, a deny or require_approval rule still counts as a candidate, and an allow rule does not.
3. Pick the most restrictive. deny beats require_approval, which beats allow. Among rules with the same effect, the first in the document wins.
4. Fall back to the default. With no candidate, the document's default applies. A require_approval default can be approved by every member with an approval role (owner, admin, approver).

The policy's effect is only one step of the decision. A policy deny ends it (POLICY_DENIED). Otherwise the Gateway still needs an organization principal (otherwise NO_PRINCIPAL), a valid delegation for the action (otherwise NO_DELEGATION) and, for require_approval, between 1 and 32 eligible approvers, each a member with a personal K-Block identity bound to their account (otherwise NO_APPROVERS or TOO_MANY_APPROVERS). The approval request's lifetime is the rule's approval_ttl_seconds, or the organization's default approval lifetime, and never longer than the delegation remains valid.

Every decision records the policy, the version, its digest and the deciding rule (or default). People in the organization see the full explanation on the action page; what the agent is told is set separately, see What agents are told.

Versions and the active version

Versions are numbered and immutable: once saved, a version's document can never be changed or deleted. You create a version by saving in the policy Editor, through the Cloud API, from a template, or as a copy of an earlier version. A rollback or an emergency stop creates a new version and activates it in the same step.

Activating a version (Activate v… in the dashboard) supersedes the previously active one and takes effect on the next call of every agent that uses the policy. Only owners and admins, signed in, can activate, roll back or stop; developers and management API keys with policies:write can create policies and draft versions but never activate them. Before activating, K-Block can refuse when saved examples fail, when the version would loosen more recent calls than you reviewed, or when the active version changed since you looked; see Activate, roll out and roll back.

Policies and versions cannot be deleted, and a policy cannot be renamed in this version. The number of policies counts toward the organization's plan limit.

Agents point at policies

An agent's policy is set when the agent is created and can be switched later by an owner or admin. Several agents can share one policy; activating a new version changes the decisions of all of them. Switching an agent to another policy ends its observe window, and an allow decided under the old policy but not yet executed is refused at execution with POLICY_CHANGED.

An allow that was decided under an older version but has not executed yet is re-checked when it executes: if the version now active would not allow it, it is refused with POLICY_CHANGED. Calls a person already approved are not re-evaluated, unless a rollback or emergency stop was told to close them.

Modes: from testing to enforcement

K-Block gives you several ways to see what a policy would do before it decides real calls. Only observe windows and the active version itself change what happens to live calls.

The require-approval stage of a rollout is not a mode of its own. It is an ordinary version derived from a target version: each deny rule becomes a guarded require_approval rule for owners and admins, and the default becomes require_approval, which any approval role (owner, admin or approver) can approve. It decides live calls once you activate it.

For each mode, see Test and simulate and Observe and shadow.

Emergency stop and rollback

Two controls let owners and admins react quickly, both taking effect on the next call of every agent that uses the policy:

• Roll back to v… activates an exact copy of an earlier version as a new version.
• Emergency stop… activates a new version that denies everything, or requires approval for everything, for every agent of that policy. It ends the agents' observe windows, and no observe window can relax it.

Both can also close actions that were decided under the replaced versions but have not executed yet. See Emergency stop.

Next steps