Skip to main content

​
Kernite Use-Case Playbooks

This guide shows how to integrate Kernite in three common scenarios:
  • LLM-driven actions
  • Building your own service/API
  • Multi-tenant SaaS platforms
The common rule is the same in all cases:
  • evaluate first with POST /execute (or managed POST /v1/execute)
  • only write when decision is approved
  • persist governance evidence with the write

​
Shared Decision Pattern

  1. Resolve scope from the write intent:
  • object_type
  • operation (create|update|delete|archive|activate)
  1. Call execute with workspace_id, principal, payload, and policy context (policy_context).
  2. If denied:
  • do not write
  • use reason_codes for remediation/retry flow
  1. If approved:
  • perform the write in the same request path (synchronous gate)
  1. Persist evidence on the write record/log:
  • hosted mode: store governance_execution_id
  • local/reference mode: store ctx_id and trace_hash
Important:
  • Do not trust a cached approved=true flag in your own DB as the authorization source.
  • Re-evaluate at write time.

​
1) LLM Actions (Function Calling / Tool Calling)

​
WHY Kernite

  • LLM output is probabilistic; write-path safety must be deterministic.
  • Agents need machine-readable deny reasons to auto-repair payloads.
  • You need verifiable decision evidence for post-incident replay.
Use execute as the synchronous gate before every external side effect.
  1. Map tool/action to governance scope.
  • POST /customers -> object_type=customer, operation=create
  • PATCH /customers/:id -> object_type=customer, operation=update
  1. Optionally map from OpenAPI operationId.
  • Customers_Create -> customer/create
  • Customers_Update -> customer/update
  1. Agent orchestrator calls execute.
  2. If denied, agent receives machine-readable reason codes and can retry with corrected payload.
  3. If approved, backend performs write immediately.

​
Async worker note

For queued jobs, evaluate in the worker right before mutation, not only at enqueue time.

​
2) Internal System / Own Service API

​
WHY Kernite

  • Route-level auth alone does not protect business write invariants.
  • Teams need one consistent guard across UI, API, workers, and actions.
  • Auditability requires explicit decision linkage, not implicit app logs.
  1. Add a write guard in every mutation endpoint/service path.
  2. Build a deterministic mapper from route/handler to scope.
  3. Call execute synchronously in the write path.
  4. Short-circuit on denied.
  5. On approved, write and persist governance evidence with the mutation log.

​
Suggested mapper inputs

  • route + method (POST /customers)
  • explicit action metadata in code
  • OpenAPI operationId
Prefer explicit mapping in code/config over ad-hoc string parsing.

​
3) Multi-Tenant SaaS

​
WHY Kernite

  • Tenant isolation needs policy decisions scoped by workspace, not global checks.
  • Zero-trust posture requires server-derived principals and fail-closed behavior.
  • Cross-tenant audit and reconciliation need stable evidence contracts.
Apply tenant-scoped execute checks as mandatory middleware in all write paths.
  1. Derive stable principal server-side (never trust client-supplied principal).
  2. Evaluate policy in the target tenant/workspace where data is mutated.
  3. Enforce fail-closed for unknown principal on governed write paths.
  4. Scope idempotency by tenant and action.
  • (workspace_id, object_type, operation, idempotency_key)
  1. Persist evidence and run reconciliation checks for writes without governance linkage.

​
Background automation

Use stable service/workflow principals. Do not use ephemeral run IDs as policy identity keys.

​
Hosted vs Local Reference

​
Hosted mode (managed)

  • Policy/execution state is persisted by the managed service.
  • Use managed execute endpoint and logs endpoint for audits.
  • Query audit trails from managed logs API.

​
Local/reference mode (kernite serve)

  • Reference server supports:
    • POST /execute
    • POST /v1/execute
    • GET /health
  • The local server is stateless by default and does not provide a persisted logs API.
  • Persist decision evidence (ctx_id, trace_hash, request metadata) in your application logs/store.

​
Audit Trail Checklist

For each successful write, keep:
  • tenant/workspace identifier
  • principal identifier
  • normalized scope (object_type, operation, target id)
  • decision metadata (ctx_id, trace_hash, reason codes)
  • linkage key (governance_execution_id in hosted mode)
  • request id / idempotency key
This enables replay, reconciliation, and incident review without relying on mutable application-only logs.