Execute API

Use execute endpoints as synchronous write guards.

POST /execute
POST /v1/execute

Decision values are only:

approved
denied

Recommended integration pattern:

Validate/normalize input.
Evaluate decision.
Mutate only on approved.
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.

Getting Started

Integrations

API

Concepts

Conformance

Library Quick Start (Python)

Request Example (Denied)

Response Shape (Denied)

Response Shape (Approved)

Policy Context Model

​Library Quick Start (Python)

​Request Example (Denied)

​Response Shape (Denied)

​Response Shape (Approved)

​Policy Context Model

Library Quick Start (Python)

Request Example (Denied)

Response Shape (Denied)

Response Shape (Approved)

Policy Context Model