Skip to main content
Use execute endpoints as synchronous write guards.
  • POST /execute
  • POST /v1/execute
Decision values are only:
  • approved
  • denied
Recommended integration pattern:
  1. Validate/normalize input.
  2. Evaluate decision.
  3. Mutate only on approved.
  4. Persist ctx_id, trace_hash, and reason metadata.

​
Library Quick Start (Python)

from kernite import evaluate_execute

request = {
    "workspace_id": "workspace-demo",
    "principal": {"type": "token", "id": "api:ops-bot"},
    "object_type": "document",
    "operation": "create",
    "payload": {"title": "Q1 Plan"},
}
result = evaluate_execute(request, idempotency_key="req-001")

decision = result["data"]["decision"]
trace_hash = result["data"]["trace_hash"]  # persist with your write/audit record
reason_codes = result["data"]["reason_codes"]

​
Request Example (Denied)

In v1, an allow policy is approved only if all its rules pass. Any rule failure produces denied with structured reasons. 
{
  "workspace_id": "workspace-demo",
  "principal": {
    "type": "token",
    "id": "api:ops-bot"
  },
  "object_type": "document",
  "operation": "create",
  "payload": {},
  "policy_context": {
    "governed": true,
    "selected_policies": [
      {
        "policy_key": "document_create_default",
        "policy_version": 1,
        "effect": "allow",
        "rules": [
          {
            "rule_key": "require_title",
            "rule_definition": {
              "type": "required_fields",
              "fields": ["title"]
            },
            "reason_code": "missing_required_fields",
            "reason_message": "title is required."
          }
        ]
      }
    ]
  }
}

​
Response Shape (Denied)

{
  "ctx_id": "ctx_...",
  "message": "Denied by governance policy.",
  "data": {
    "decision": "denied",
    "reason_codes": ["missing_required_fields"],
    "reasons": [
      {
        "code": "missing_required_fields",
        "message": "title is required.",
        "rule_key": "require_title",
        "field_path": "payload.title",
        "details": {
          "missing_fields": ["title"]
        }
      }
    ],
    "policy_selection_reason_code": "policy_selected_workspace_default",
    "policy": {
      "policy_key": "document_create_default",
      "policy_version": 1
    },
    "trace_hash": "sha256:...",
    "idempotency_key": "..."
  }
}

​
Response Shape (Approved)

{
  "ctx_id": "ctx_...",
  "message": "Approved by governance policy.",
  "data": {
    "decision": "approved",
    "reason_codes": [],
    "reasons": [],
    "policy_selection_reason_code": "policy_selected_workspace_default",
    "policy": {
      "policy_key": "document_create_default",
      "policy_version": 1
    },
    "trace_hash": "sha256:...",
    "idempotency_key": "..."
  }
}

​
Policy Context Model

policy_context is optional, but recommended for production. Kernite evaluates policies supplied in policy_context.selected_policies. In OSS mode, Kernite does not fetch policy state from storage. Main fields:
  • governed (bool): request is enforced as governed scope
  • selected_policies (array): policies selected by your resolver
  • governed_scopes (array): optional scope list (object_type + operation)
  • policy_selection_reason_code (string): explicit selection reason
Default behavior:
  • governed + no selected policy => denied with no_matching_policy
  • not governed + no selected policy => approved with out_of_scope_phase1
For full contract invariants, see /concepts/compatibility.