Create a policy

A policy decides, for every tool call of the agents assigned to it, whether the call is allowed, denied or held for a person's approval. You write it as a JSON document, save it as a numbered version, and an owner or admin activates one version to make it decide calls.

Nothing you create or save on this page affects a live call until a version is activated. Until then, every call of an agent that uses the policy is denied with NO_POLICY, because the policy has no active version.

Who can do what

Activation requires a signed-in owner or admin. A management API key with the policies:write scope can create policies and drafts, but no API key can activate a version. See Roles and permissions and API keys.

Before you start

A policy matches calls by their action, the permission name you gave each tool when you exposed it (for example refund.issue), and optionally by the exposed tool name and the call's amount. Expose and map your tools first, so the editor and the template coverage report can check your rules against them. See Expose and map tools.

Create the policy

1. Open the new-policy page

   In the dashboard, open Policies and select New policy. Only owners, admins and developers see the button; other roles who open the new-policy page see a notice instead of the form.

2. Choose a starting point

   Under Start from, pick one card:

   • Blank (deny-all): an empty policy. The editor starts from a document with no rules and a deny default, so every call is denied until you add rules.
   • A template, such as Support refunds or Finance operations: a complete example document with rules, saved example calls and a recommended rollout. See Templates for the five templates and their parameters.

3. Name it and set the parameters

   Enter a Name (required, up to 200 characters, unique in the organization) and an optional Description. For a template, fill in its Parameters, for example the currency and the amount limits. The preview on the right shows the template with its default parameters.

4. Create it

   • For a blank policy, select Create policy. K-Block creates the policy without any version and opens its Editor tab. Version 1 exists only after you save the document.
   • For a template, select Create draft. K-Block creates the policy with draft v1, built from your parameters, and saves the template's example calls as the policy's saved examples. The page then shows Coverage of your tools (which of your enabled tools the rules match, and which fall to the default), the Decision map, the saved example calls and the draft's document. Select Open the policy to continue.

Templates assume action names such as refund.issue or payments.send. Compare them with your tools' actions in the coverage report and adapt the document before you activate it.

Errors when creating a policy

The policy page

Each policy has a page with a summary (active version, when and by whom it was activated, shadow version, number of agents, digest) and six tabs:

Edit the document

The Editor tab holds the policy document as JSON text. It opens with the active version's document, or the newest version if none is active, or the empty deny-all document for a new blank policy. Selecting Open on any version in the Versions tab loads that version into the editor.

The editor is a plain JSON text area; there is no form-based rule builder. The document format is described in Rules, amounts and currencies. Owners, admins and developers can edit; for approvers and viewers the editor is read-only.

Next to the editor, the Reference card lists your exposed tools with their actions and amount currency, and the members who can approve, with the user IDs you can use in approvers.users. It shows at most the first 100 tools and the approval-capable members among the first 100 members.

Validate

Select Validate on server. Any member can validate; validation never saves anything. The server checks the whole document and reports every problem at once, each with a JSON Pointer path such as /rules/2/approvers. It also checks that every user listed as an approver is a current member with an approval-capable role.

When the document is valid, the editor shows:

• Valid and the document's digest (sha256:…), the fingerprint that will identify this version;
• the language revision: revision 1 for documents without rule description or guard members, revision 2 otherwise. A revision-2 document can be activated only once K-Block has enabled these newer policy features on every Gateway; until then the editor shows Activation blocked with the reason, and activation is refused with GATEWAYS_NOT_UPGRADED. Try again later (if activation keeps being refused, contact K-Block support with the error code and the time of your attempt), or remove the rule descriptions and guards to save a revision-1 version (see the language gate);
• advisory warnings. They never make a document invalid:

If the document uses rule descriptions, the editor also reminds you that Descriptions are shown to agents. Never put secrets in them.

Save a draft version

Optionally enter a Note for this version (what changed and why, up to 1000 characters), then select Save as new version. K-Block validates the document again and stores it as the next numbered version with status draft. Saving changes nothing for live calls.

Every saved version is immutable: its document and digest can never change. To change a policy, you save another version. See Versions.

Activate

A draft decides nothing until an owner or admin activates it. Before you activate, test it: run its saved examples and try calls on the Test tab, and replay recorded calls on the Simulate tab (Test and simulate).

To activate, an owner or admin selects Activate on the draft in the Versions tab, or Review and activate v… on the Rollout tab. The activation sheet shows what changes compared with the active version, a simulation over the last 7 days of recorded calls, the saved examples, the agents in observe mode and the Gateway language check. After confirmation, the version decides the next call of every agent assigned to the policy.

The activation gates, the refusals and how to undo an activation are described in Activate, roll out and roll back.

Do the same through the Cloud API

Every step above is a Cloud API request under /api/v1:

See the Cloud API reference for the full request and response shapes.

Next steps