Skip to main content

Govern check — runtime API

POST /v1/govern/check is the transport-agnostic policy decision point for agents that are not (or not only) MCP: LangChain, CrewAI, OpenAI tools, custom HTTP workers, and anything that can call HTTPS before invoking a tool.

MCP clients should prefer the Agent Gateway (/mcp/*). Both paths seal decisions into the evidence ledger.

Prerequisites​

  1. Register an agent identity (console or POST /v1/agent-identities).
  2. Set allowedTools (e.g. ledger.query, github.*, or *).
  3. Approve with one of:
    • Enterprise: configure IdP → approve-external (bind Okta/Entra/OIDC subject) — agent uses its IdP JWT
    • Lab: mint uvt_… (shown once)
  4. In production, a different admin must approve (separation of duties).
export UNVEILR_API=https://guard.unveilr.ai
# Enterprise (preferred): JWT from your IdP
export UNVEILR_AGENT_TOKEN="$IDP_JWT"
# Lab fallback:
# export UNVEILR_AGENT_TOKEN=uvt_…

See Enterprise agent identity.

Request​

POST /v1/govern/check
Authorization: Bearer <IdP JWT or uvt_…>
Content-Type: application/json
{
  "tool": "ledger.query",
  "server": "ledger",
  "arguments": { "sql": "select 1" }
}
FieldRequiredNotes
toolyesTool name to authorize
servernoNamespace / MCP server id
argumentsnoObject scanned for injection / policy

Response​

{
  "decision": "allow",
  "reason": "…",
  "agent": "payments-bot",
  "findings": [],
  "maxSeverity": null,
  "evidenceId": "evt_…"
}
decisionMeaning
allowProceed with the tool call
denyDo not call the tool; surface reason / findings

Fail closed: missing, revoked, expired, unbound, or unapproved credentials → 401 / 403 (not a soft allow).

curl​

curl -fsS -X POST "$UNVEILR_API/v1/govern/check" \
  -H "Authorization: Bearer $UNVEILR_AGENT_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tool":"ledger.query","server":"ledger","arguments":{"sql":"select 1"}}'

Verify out-of-scope deny:

curl -fsS -X POST "$UNVEILR_API/v1/govern/check" \
  -H "Authorization: Bearer $UNVEILR_AGENT_TOKEN" \
  -H "content-type: application/json" \
  -d '{"tool":"shell.exec","arguments":{"cmd":"id"}}'

Python SDK​

pip install -e /path/to/unveilr-guard/sdk/python
from unveilr import govern

@govern(tool="ledger.query", server="ledger")
def query_ledger(sql: str):
    ...

Adapters: unveilr.langchain, unveilr.crewai, unveilr.openai_tools, unveilr.langgraph. Env: UNVEILR_API, UNVEILR_AGENT_TOKEN.

Node SDK​

import { requireAllow } from "@unveilr/govern"; // or sdk/js path

await requireAllow(
  "ledger.query",
  { sql: "select 1" },
  { server: "ledger" }
);

On-ramp snippets​

After approve, fetch copy-paste helpers:

curl -fsS "$UNVEILR_API/v1/agent-identities/{id}/onramp" \
  -H "Authorization: Bearer $ADMIN_JWT"

Or use On-ramp in the console Agents UI.

Evidence & SIEM​

Every check appends a policy_decision evidence event. View in console Evidence / Sessions, or:

curl -fsS "$UNVEILR_API/v1/evidence/export?since=2026-01-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Live push: Settings → Notifications → type SIEM or webhook.

Kill switch​

curl -fsS -X POST "$UNVEILR_API/v1/agent-identities/{id}/revoke" \
  -H "Authorization: Bearer $ADMIN_JWT"

Subsequent govern checks fail closed immediately.

Acceptance checklist​

  • In-scope tool → allow + evidenceId
  • Out-of-scope / injection → deny
  • Both visible in Evidence
  • Revoke → credential rejected
  • Onboarding step Run one Govern check completes