Governance Controls

Quick example

curl
Python
Node.js

# Open an L4 breaker on a specific provider
curl "$TRINITITE_BASE/v1/governance/breakers/openai" \
  -H "Authorization: Bearer $TRINITITE_API_KEY" \
  -X POST -d '{"state":"open","reason":"upstream incident"}'

import os, requests
requests.post(f"{os.environ['TRINITITE_BASE']}/v1/governance/breakers/openai",
    headers={"Authorization": f"Bearer {os.environ['TRINITITE_API_KEY']}"},
    json={"state": "open", "reason": "upstream incident"})

await fetch(`${process.env.TRINITITE_BASE}/v1/governance/breakers/openai`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.TRINITITE_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ state: 'open', reason: 'upstream incident' }),
});

See Governance Controls for the L0-L6 control hierarchy.

Overview

The control-plane knobs an enterprise needs to operate the platform safely:

Stop a rogue agent immediately — single-NHI suspension, org-wide kill switch, manual breaker trip.
Set safe defaults — org-wide governance posture, default spend caps, model allow / block lists.
Override per-agent — give a trusted orchestrator a higher cap, restrict an experimental agent to specific models.
Harden the data plane — manually open / close circuit breakers when a downstream provider is misbehaving.
See everything — a unified event stream of every significant governance action.

Authentication: Authorization: Bearer <session_token | api_key> with the relevant permission. Most /v1/admin/* endpoints require the admin system role.

Control hierarchy

Controls are layered. The most restrictive wins.

Level 0  Emergency shutdown                  Org-wide kill switch
Level 1  Org governance settings             Mode, default spend, model lists
Level 2  Per-NHI governance profile          Agent-level overrides
Level 3  Economic session                    Per-session spend cap & breaker
Level 4  Inference / MCP-pool breakers       Data-plane health
Level 5  Per-tool retry cap                  Per-tool execution limit
Level 6  IMDS shield                         Egress URL validation

Per-tool Guardian bindings on the MCP Gateway layer on top — they can fail-closed where org-level governance would fail-open.

Endpoints

Org governance settings

Method	Path	Permission
`GET`	`/v1/organization/settings/governance`	`organization:read`
`PATCH`	`/v1/organization/settings/governance`	`organization:update`

Emergency

Method	Path	Permission
`POST`	`/v1/admin/emergency/shutdown`	`admin`
`POST`	`/v1/admin/emergency/resume`	`admin`
`GET`	`/v1/admin/emergency/status`	`admin`
`POST`	`/v1/admin/emergency/suspend-agent/{nhiId}`	`admin`

Circuit breakers

Method	Path	Permission
`GET`	`/v1/admin/circuit-breakers`	`admin`
`POST`	`/v1/admin/circuit-breakers/{name}/open`	`admin`
`POST`	`/v1/admin/circuit-breakers/{name}/close`	`admin`
`POST`	`/v1/admin/circuit-breakers/{name}/reset`	`admin`

Per-NHI governance profile

Method	Path	Permission
`GET`	`/v1/proxy/nhi/{nhiId}/governance-profile`	`nhi:read`
`PATCH`	`/v1/proxy/nhi/{nhiId}/governance-profile`	`nhi:update`

Credential controls

Method	Path	Permission
`PATCH`	`/v1/proxy/credentials/{id}/controls`	`provider_credentials:create`

Event stream

Method	Path	Permission
`GET`	`/v1/admin/governance/events`	`admin`

Global-Intel auto-Guardian

Method	Path	Permission
`POST`	`/v1/global-intel/auto-guardian-actions/process`	`agentic_risk:configure`

Org governance settings

GET /v1/organization/settings/governance

{
  "organization_id": "org_01JF8RORG1A2B3C4D5E6F7G8H9I",
  "governance_mode": "enforce",
  "emergency_shutdown": false,
  "emergency_shutdown_at": null,
  "emergency_shutdown_reason": null,
  "default_spend_limit_usd": 5.0,
  "default_session_ttl_hours": 8,
  "max_concurrent_sessions": 100,
  "max_token_budget_per_session": null,
  "max_token_budget_per_hour": null,
  "streaming_governance_enabled": true,
  "allowed_models": null,
  "blocked_models": ["gpt-3.5-turbo", "gpt-3.5-turbo-instruct"],
  "max_spawn_depth_default": 3
}

Field	Type	Description
`governance_mode`	`enforce` / `monitor` / `bypass`	Org-wide posture
`emergency_shutdown`	`boolean`	Kill-switch state
`default_spend_limit_usd`	`number`	Default cap for new economic sessions
`default_session_ttl_hours`	`integer`	Default TTL for new sessions
`max_concurrent_sessions`	`integer`	Org-wide cap
`max_token_budget_per_session` / `_per_hour`	`integer \| null`	Optional token caps
`streaming_governance_enabled`	`boolean`	Run post-stream spend accounting on streaming requests
`allowed_models` / `blocked_models`	`string[] \| null`	Override credential-level allowlists
`max_spawn_depth_default`	`integer`	Default spawn depth for new NHIs

PATCH /v1/organization/settings/governance

Partial update. Changes to governance_mode affect new requests only; in-flight requests are not interrupted. Use the emergency shutdown to halt traffic immediately.

Emergency controls

The kill switch is checked before any NHI validation, breaker, or Guardian evaluation. It is the most powerful control.

POST /v1/admin/emergency/shutdown

{ "reason": "Investigating suspected credential leak" }

Activates the kill switch. Every /v1/proxy/* request immediately returns 503 emergency_shutdown with the reason. Returns the updated org settings object.

POST /v1/admin/emergency/resume

Clears the kill switch.

GET /v1/admin/emergency/status

{
  "emergency_shutdown": true,
  "emergency_shutdown_at": "2026-05-01T22:14:00Z",
  "emergency_shutdown_reason": "Investigating suspected credential leak",
  "actor": { "user_id": "usr_01JF...", "display_name": "Jane Doe" }
}

POST /v1/admin/emergency/suspend-agent/{nhiId}

Suspend a single NHI without affecting the rest of the fleet. Active sessions and JIT tokens for the NHI are immediately invalidated. Body: { "reason": "..." }.

Circuit breakers

The platform tracks several named circuit breakers across the data plane. GET /v1/admin/circuit-breakers returns every breaker with its current state and recent transitions.

{
  "breakers": [
    {
      "name": "openai_inference",
      "state": "CLOSED",
      "failure_count": 0,
      "last_state_change_at": "2026-05-01T08:14:00Z",
      "last_failure_at": null
    },
    {
      "name": "anthropic_inference",
      "state": "OPEN",
      "failure_count": 47,
      "last_state_change_at": "2026-05-01T22:08:00Z",
      "last_failure_at": "2026-05-01T22:09:11Z"
    }
  ]
}

State	Meaning
`CLOSED`	Healthy, traffic flows
`OPEN`	Tripped, requests fail fast
`HALF_OPEN`	Probing — allowing limited traffic to test recovery

Manual operations:

Endpoint	Effect
`POST .../{name}/open`	Force-open the breaker (e.g. when you know an upstream is degraded but the breaker hasn't tripped yet)
`POST .../{name}/close`	Force-close the breaker
`POST .../{name}/reset`	Reset failure counters

All operations write to the governance event stream.

Per-NHI governance profile

Per-agent overrides. Unset fields fall back to org-wide defaults.

GET / PATCH /v1/proxy/nhi/{nhiId}/governance-profile

{
  "nhi_id": "nhi_01JF8RNHI1A2B3C4D5E6F7G8H9",
  "governance_mode": "enforce",
  "spend_limit_usd": 25.0,
  "session_ttl_hours": 24,
  "allowed_models": ["gpt-4o", "claude-3-5-sonnet-latest"],
  "blocked_models": null,
  "max_concurrent_sessions": 5,
  "streaming_governance_enabled": true
}

PATCH performs a field-level upsert — only the fields you send are changed.

Credential controls

Per-credential spend cap, RPM throttle, and disable switch. See Provider Credentials for the credential lifecycle itself.

PATCH /v1/proxy/credentials/{id}/controls

{
  "monthly_spend_cap_usd": "10000.00",
  "rpm_limit": 600,
  "disabled": false
}

Field	Type	Description
`monthly_spend_cap_usd`	decimal `string \| null`	Hard cap (USD). `null` means unbounded
`rpm_limit`	`integer \| null`	Requests-per-minute
`disabled`	`boolean`	When `true`, every call against the credential returns `403 credential_disabled`

Cap breach trips the credential into a soft-fail state that returns 429 credential_spend_cap until the next billing cycle (or a manual reset via POST .../reset on the matching breaker).

Governance event stream

GET /v1/admin/governance/events

Append-only audit row for any significant control-plane action across the platform.

Query	Type	Description
`event_type`	`string`	Filter to one event type
`severity`	`string`	`info`, `warning`, `error`, `critical`
`subsystem`	`string`	`emergency`, `breaker`, `economic_session`, `governance_profile`, `credential_controls`, `auto_guardian`, `governance_settings`
`from` / `to`	RFC 3339	Time window
`limit` / `cursor`	—	Cursor pagination

{
  "data": [
    {
      "event_id": "gev_01JF8RGE1A2B3C4D5E6F7G8H9I",
      "event_type": "emergency.shutdown.activated",
      "subsystem": "emergency",
      "severity": "critical",
      "actor": { "user_id": "usr_01JF...", "display_name": "Jane Doe" },
      "detail": {
        "reason": "Investigating suspected credential leak",
        "previous_mode": "enforce"
      },
      "request_id": "req_01J...",
      "occurred_at": "2026-05-01T22:14:00Z"
    },
    {
      "event_id": "gev_01JF8RGE2B3C4D5E6F7G8H9I0J",
      "event_type": "breaker.openai_inference.opened",
      "subsystem": "breaker",
      "severity": "warning",
      "detail": { "failure_count": 47, "trigger": "auto" },
      "occurred_at": "2026-05-01T22:08:00Z"
    }
  ],
  "page": { "next_cursor": null, "has_more": false }
}

Common event types:

Event type	Source
`emergency.shutdown.activated` / `.cleared`	Emergency controls
`breaker.{name}.{opened\|closed\|reset}`	Circuit breakers
`economic_session.tripped` / `.reset`	Per-NHI economic sessions
`governance_profile.updated`	Per-NHI profile PATCH
`credential_controls.updated`	`PATCH /v1/proxy/credentials/{id}/controls`
`governance_settings.updated`	Org governance settings PATCH
`auto_guardian.action.applied`	Global-Intel auto-Guardian

Global-Intel auto-Guardian

POST /v1/global-intel/auto-guardian-actions/process

Process a queue of automatic responses to external threat signals (e.g. "advisory disclosed against kubectl < 1.30 — quarantine all skills with tools_required:kubectl"). Returns a summary of actions applied.

{
  "applied": 3,
  "skipped": 1,
  "failed": 0,
  "actions": [
    { "action_id": "ag_01JF...", "type": "skill.revoke", "target": "sk_01JF...", "status": "applied" },
    { "action_id": "ag_01JF...", "type": "guardian.retrain", "target": "gov_01JF...", "status": "applied" }
  ]
}

Configuration of which signals trigger which actions is an enterprise feature — contact your account team.

Errors

HTTP	`error.code`	Cause
`400`	`validation_error`	Body or query failed schema validation
`401`	`unauthenticated`	Missing or invalid credential
`403`	`forbidden`	Caller lacks the required permission (most `/v1/admin/*` endpoints require the `admin` role)
`404`	`not_found`	NHI, credential, or breaker not found
`409`	`conflict`	Emergency shutdown already active / already cleared; breaker already in target state
`503`	`emergency_shutdown`	Org-wide kill switch is engaged (returned by all proxy endpoints, not the controls themselves)

Next steps

Define what an emergency means — set defaults → Org settings GET / PATCH
See every control change in one place → Governance event stream
Suspend a single agent without org-wide impact → /v1/admin/emergency/suspend-agent/{nhiId}
Manage the agents being suspended → Identities

Quick example​

Overview​

Control hierarchy​

Endpoints​

Org governance settings​

Emergency​

Circuit breakers​

Per-NHI governance profile​

Credential controls​

Event stream​

Global-Intel auto-Guardian​

Org governance settings​

GET /v1/organization/settings/governance​

PATCH /v1/organization/settings/governance​

Emergency controls​

POST /v1/admin/emergency/shutdown​

POST /v1/admin/emergency/resume​

GET /v1/admin/emergency/status​

POST /v1/admin/emergency/suspend-agent/{nhiId}​

Circuit breakers​

Per-NHI governance profile​

GET / PATCH /v1/proxy/nhi/{nhiId}/governance-profile​

Credential controls​

PATCH /v1/proxy/credentials/{id}/controls​

Governance event stream​

Global-Intel auto-Guardian​

Errors​

Next steps​

Quick example

Overview

Control hierarchy

Endpoints

Org governance settings

Emergency

Circuit breakers

Per-NHI governance profile

Credential controls

Event stream

Global-Intel auto-Guardian

Org governance settings

GET /v1/organization/settings/governance

PATCH /v1/organization/settings/governance

Emergency controls

POST /v1/admin/emergency/shutdown

POST /v1/admin/emergency/resume

GET /v1/admin/emergency/status

POST /v1/admin/emergency/suspend-agent/{nhiId}

Circuit breakers

Per-NHI governance profile

GET / PATCH /v1/proxy/nhi/{nhiId}/governance-profile

Credential controls

PATCH /v1/proxy/credentials/{id}/controls

Governance event stream

Global-Intel auto-Guardian

Errors

Next steps