Governance Signal Integration API

The bridge between business governance and security enforcement. External systems (FinOps, CLM, compliance platforms) push governance signals to AuthHub. Policies evaluate those signals and apply enforcement actions (throttle, suspend, require attestation, downgrade) in under 2 seconds.

Base Path

/api/v1/tenant/governance

All endpoints require X-Tenant-ID and Authorization: Bearer headers.

Signal Lifecycle

1Source Registration — Register external systems that will send signals (FinOps, CLM, etc.)
2Policy Configuration — Define what enforcement action each signal type triggers
3Signal Ingestion — External system pushes a signal (e.g., “budget exceeded”)
4Policy Evaluation — Matched policies determine enforcement action and scope
5Enforcement — Applied to Redis + PDP within 2 seconds (throttle, suspend, attestation, etc.)
6Resolution — Signal expires, is resolved, or is overridden. Enforcement reverts automatically.

Enforcement Actions

Action	Effect	Reversible?
throttle	Rate-limit affected subjects/agents	Auto-reverts on resolution
suspend	Block all access for scope	Auto-reverts on resolution
require_attestation	Push attestation to decision owner, block until approved	Reverts when attested
downgrade	Reduce capability (e.g., model tier GPT-4 → GPT-3.5)	Auto-reverts on resolution
audit_only	Log the event, no enforcement (monitoring mode)	N/A
model_routing_override	Route requests to alternative model endpoint	Auto-reverts
custom_webhook	Call external webhook for custom enforcement logic	Depends on webhook

Signal Sources

Register external systems that push governance signals. Each source is authenticated (mTLS, OAuth, or HMAC) and rate-limited independently.

GET/api/v1/tenant/governance/signal-sources

List all registered signal sources for the tenant.

POST/api/v1/tenant/governance/signal-sources

Request BodyJSON

{
  "name": "FinOps - AWS Cost Explorer",
  "description": "Budget threshold alerts from AWS FinOps pipeline",
  "authMethod": "oauth",
  "authConfig": {
    "client_id": "finops-bridge-001",
    "audience": "https://authhub.cloud/governance"
  },
  "allowedSignalTypes": ["budget_exceeded", "budget_warning", "spend_anomaly"],
  "rateLimitPerMinute": 60,
  "ipAllowlist": ["10.0.0.0/8"],
  "operationalMode": "production",
  "freshnessWindowHours": 1,
  "staleBehaviour": "alert_only"
}

Response (201)JSON

{
  "source": {
    "id": "src-uuid",
    "tenantId": "tenant-uuid",
    "name": "FinOps - AWS Cost Explorer",
    "authMethod": "oauth",
    "operationalMode": "production",
    "enabled": true,
    "createdAt": "2026-08-13T10:00:00Z"
  }
}

Freshness monitoring: Sources that don't send a heartbeat within freshnessWindowHoursare flagged as stale. The staleBehaviour controls the response: alert only, revert enforcement, or escalate.

Signal Ingestion

Push governance signals from external systems. Signals are evaluated against policies immediately and enforcement is applied within 2 seconds.

POST/api/v1/tenant/governance/signals

Ingest a single governance signal.

Request BodyJSON

{
  "signalId": "fin-alert-2026-08-13-001",
  "signalType": "budget_exceeded",
  "sourceSystem": "aws-finops",
  "severity": "critical",
  "affectedScope": {
    "scopeType": "agent",
    "scopeIds": ["clinical-summariser-prod", "discharge-bot-v2"]
  },
  "payload": {
    "budgetName": "AI-Agents-Q3-2026",
    "threshold": 10000,
    "actualSpend": 12450,
    "currency": "GBP",
    "period": "2026-08-01/2026-08-31"
  },
  "expiresAt": "2026-08-31T23:59:59Z",
  "decisionOwner": "vp-engineering@nhs.net"
}

Response (202)JSON

{
  "signalId": "fin-alert-2026-08-13-001",
  "status": "accepted",
  "enforcementApplied": "throttle",
  "traceId": "trace-uuid"
}

POST/api/v1/tenant/governance/signals/bulk

Ingest multiple signals in a single batch (max 100).

POST/api/v1/tenant/governance/signals/simulate

Simulate a signal without applying enforcement. Returns matched policies and what would happen.

Simulation Response (200)JSON

{
  "matchedPolicies": [
    { "policyId": "pol-uuid", "name": "AI Budget Gate", "action": "throttle" }
  ],
  "enforcementDecision": {
    "action": "throttle",
    "parameters": { "maxRequestsPerMinute": 10 },
    "priority": 100
  },
  "affectedSubjects": ["clinical-summariser-prod", "discharge-bot-v2"],
  "conflicts": [],
  "wouldApply": true
}

Supported Signal Types

AuthHub supports 17 built-in signal types across 9 governance domains, plus unlimited custom tenant-defined types. Each signal type has a registered schema, default enforcement action, and priority level.

Regulatory & Compliance

Signal Type	Payload (key fields)	Default Enforcement
regulatory_risk_classification	modelId, classification (unacceptable\|high_risk\|limited_risk\|minimal_risk), jurisdiction, regulatoryFramework	high_risk → require_attestation; unacceptable → suspend
data_sovereignty_mismatch	subjectLocation, modelDeploymentRegion, dataClassification, violatedRegulation, compliantAlternatives[]	model_routing_override (to compliant region); suspend if no alternative
consent_revoked	subjectId, consentScope (training_data_usage\|third_party_sharing\|profiling), revokedAt, legalBasis	suspend + emit data_retention_purge_required

Responsible AI & Model Health

Signal Type	Payload (key fields)	Default Enforcement
bias_detected	modelId, metric (demographic_parity\|equalized_odds), value, threshold, protectedAttribute, affectedSegment	downgrade to sandbox; critical (>20% disparity) → require fairness attestation
hallucination_rate_exceeded	agentId, factualAccuracy, sourceGroundingScore, evaluatorSystem, sampleSize	model_routing_override (deterministic/low-temperature)
safety_filter_triggered	agentId, subjectId, safetyCategory (toxic_output\|jailbreak_attempt\|prompt_injection), count, window	throttle (1%); escalate on >3 in 5min → suspend + security alert

Security & Supply Chain

Signal Type	Payload (key fields)	Default Enforcement
vulnerability_disclosed	affectedComponent, cveId, cvssScore, patchAvailable, exploitPublic	CVSS ≥9.0 → suspend; ≥7.0 → throttle; ≥4.0 → audit_only
sensitive_data_exposure	subjectId, detectedEntities[] (SSN\|API_key\|NHS_number\|PII), dataMaskingApplied, activeSessionId	audit_only + mid-stream termination if session active
shadow_ai_detected	subjectId, unapprovedModelId, inferenceVolume, discoveryMethod	throttle → suspend after 7 days if unresolved

Dataset & Data Lifecycle

Signal Type	Payload (key fields)	Default Enforcement
training_data_revoked	datasetFingerprint, revocationReason (copyright_takedown\|DSAR_erasure\|poison_detected), affectedModelIds[]	suspend (no auto-revert — manual revalidation required)
dataset_drift_detected	datasetFingerprint, driftType (concept_drift\|covariate_shift), driftScore, affectedModelIds[]	downgrade to sandbox; critical (score >0.5) → suspend

Financial & Commercial

Signal Type	Payload (key fields)	Default Enforcement
budget_threshold_exceeded	costCenterId, budgetId, currentSpend, budgetLimit, percentUsed, period	≥80% → require_attestation; ≥100% → throttle; ≥120% → suspend
contract_status_changed	vendorId, contractId, newStatus (active\|expiring\|expired\|terminated\|non_compliant), affectedServices[]	expired/terminated → suspend; non_compliant → audit_only
pilot_status_changed	pilotId, agentId, status (active\|expired\|value_proven\|value_unproven), expiryDate	expired + value_unproven → downgrade to sandbox

Workforce & ESG

Signal Type	Payload (key fields)	Default Enforcement
employee_status_changed	subjectId, newStatus (offboarded\|on_leave\|role_changed), effectiveDate, securityIncident	offboarded → suspend + NHI self-repair; on_leave → downgrade
certification_lapsed	subjectId, certificationName, expiryDate, gracePeriodDays	audit_only; escalate to suspend after grace period (14d default)
periodic_recertification_due	subjectIds[], reviewCycle, reviewName, deadline, grcPlatform	require_attestation; auto-suspend after 30 days unresolved
carbon_budget_exceeded	metric (gCO2e_per_token\|total_kWh), period, currentValue, threshold, reportingFramework	model_routing_override to lightweight SLM (exclude Tier 0-1)

Priority hierarchy: Regulatory (50) > Security (60) > Safety (70) > Responsible AI (80) > Model Health (90) > Workforce (100) > Certifications (150) > Financial (200) > Operational (250) > ESG (300) > Custom (400). Lower number = higher enforcement priority. When signals conflict, the highest-priority wins.

GET/api/v1/tenant/governance/schemas/:signalType

Retrieve the JSON Schema for a specific signal type (built-in or custom).

Signal Policies

Policies define what enforcement action to take when a signal of a given type and severity is received. Policies are evaluated in priority order; the first matching policy wins.

GET/api/v1/tenant/governance/signal-policies

List all signal policies.

POST/api/v1/tenant/governance/signal-policies

Create a new signal policy.

Request BodyJSON

{
  "name": "AI Budget Gate — Critical",
  "signalType": "budget_exceeded",
  "severityThreshold": "critical",
  "celCondition": "payload.actualSpend > payload.threshold * 1.2",
  "enforcementAction": "suspend",
  "actionParameters": {
    "message": "AI spend exceeded 120% of budget. VP approval required to resume."
  },
  "affectedScopeSelector": { "scopeType": "agent", "scopeIds": ["*"] },
  "priority": 100,
  "debounceSeconds": 300,
  "autoRevert": true,
  "enabled": true
}

CEL conditions: Policies support Common Expression Language (CEL) for fine-grained matching. Access payload.*, severity, sourceSystem, and affectedScope.* in expressions.

Active Signals

Query signals currently in effect — with enforcement state, resolution status, and audit trail.

GET/api/v1/tenant/governance/signals/active

List all currently active (unresolved) signals.

GET/api/v1/tenant/governance/signals/history

List historical signals (resolved, expired, superseded). Supports cursor pagination.

GET/api/v1/tenant/governance/signals/conflicts

List signals where multiple policies matched with conflicting enforcement actions.

Active Signal ResponseJSON

{
  "data": [
    {
      "id": "sig-uuid",
      "signalId": "fin-alert-2026-08-13-001",
      "signalType": "budget_exceeded",
      "severity": "critical",
      "status": "active",
      "sourceId": "src-uuid",
      "affectedScope": { "scopeType": "agent", "scopeIds": ["clinical-summariser-prod"] },
      "enforcementAction": "throttle",
      "enforcementAppliedAt": "2026-08-13T10:00:01Z",
      "decisionOwner": "vp-engineering@nhs.net",
      "expiresAt": "2026-08-31T23:59:59Z",
      "createdAt": "2026-08-13T10:00:00Z"
    }
  ]
}

Enforcement State

Query the current enforcement state for a subject, agent, or scope. This is what the PDP checks on every authorization request (via Redis L1 cache — sub-millisecond).

GET/api/v1/tenant/governance/enforcement/:subjectId

Get active enforcement for a specific subject.

Response (200)JSON

{
  "subjectId": "clinical-summariser-prod",
  "enforcements": [
    {
      "signalId": "fin-alert-2026-08-13-001",
      "action": "throttle",
      "parameters": { "maxRequestsPerMinute": 10 },
      "priority": 100,
      "appliedAt": "2026-08-13T10:00:01Z",
      "expiresAt": "2026-08-31T23:59:59Z"
    }
  ],
  "overrideActive": false
}

PDP integration: On every auth request, the PDP checks Redis keygov:signal:enforcement:<tenant>:<scope_type>:<scope_id>. If present, the enforcement action is applied inline — zero additional network calls.

Common-Exposure Conditions

Track shared dependencies (model providers, data processors, regulatory conditions) as versioned entities. When one condition changes, all dependents are assessed for exposure.

GET/api/v1/tenant/governance/conditions

List all registered conditions.

POST/api/v1/tenant/governance/conditions

GET/api/v1/tenant/governance/conditions/:type

Get a specific condition by type.

GET/api/v1/tenant/governance/conditions/:type/versions

Version history for a condition.

GET/api/v1/tenant/governance/conditions/:type/dependents

Backward traversal: which subjects/agents depend on this condition?

GET/api/v1/tenant/governance/conditions/:type/exposure

Current exposure level for a condition.

GET/api/v1/tenant/governance/exposure-events

List exposure events (condition non-compliance detected).

POST/api/v1/tenant/governance/exposure-events/:id/promote

Promote an exposure event to a governance signal (triggers enforcement).

POST/api/v1/tenant/governance/exposure-events/:id/dismiss

Dismiss an exposure event (false positive or accepted risk).

Condition ExampleJSON

{
  "conditionType": "openai-dpa",
  "displayName": "OpenAI Data Processing Agreement",
  "currentVersion": 3,
  "currentValue": "DPA v3.1 — EU data residency, no training on customer data",
  "status": "compliant",
  "dependents": 12,
  "lastAssessedAt": "2026-08-10T14:00:00Z"
}

Drift Declarations

Declare environmental changes (vendor migrations, infrastructure moves, regulatory shifts) that may invalidate existing attestations. Affected subjects are flagged for re-assessment.

GET/api/v1/tenant/governance/drift-declarations

List all drift declarations.

POST/api/v1/tenant/governance/drift-declarations

Create a new drift declaration.

Request BodyJSON

{
  "driftType": "vendor_migration",
  "description": "Migrating from OpenAI to Anthropic for clinical summarisation",
  "affectedConditions": ["openai-dpa"],
  "affectedAgents": ["clinical-summariser-prod", "discharge-bot-v2"],
  "effectiveDate": "2026-09-01T00:00:00Z",
  "requiresReAttestation": true,
  "declaredBy": "platform-architect@nhs.net"
}

Cost Centres

Map subjects and agents to cost centres for budget enforcement. When a FinOps signal targets a cost centre, all assigned subjects receive the enforcement action.

GET/api/v1/tenant/governance/cost-centres

List all cost centres with assignment counts.

POST/api/v1/tenant/governance/cost-centres

Create or import cost centres.

Request BodyJSON

{
  "costCentres": [
    {
      "code": "CC-4200",
      "name": "AI Clinical Agents",
      "department": "Digital Health",
      "budgetOwner": "vp-digital@nhs.net",
      "monthlyBudget": 10000,
      "currency": "GBP",
      "subjectIds": ["clinical-summariser-prod", "discharge-bot-v2", "triage-assistant"]
    }
  ]
}

Overrides & Decisions

Emergency overrides temporarily bypass enforcement for specific subjects. Overrides are time-bounded, require a named approver, and auto-expire.

GET/api/v1/tenant/governance/overrides

List active and historical overrides.

POST/api/v1/tenant/governance/overrides

Create an emergency override.

Request BodyJSON

{
  "subjectIds": ["clinical-summariser-prod"],
  "reason": "Patient safety: summariser needed for critical care discharge despite budget cap",
  "approvedBy": "clinical-safety-officer@nhs.net",
  "durationMinutes": 240,
  "notifyOnExpiry": ["vp-engineering@nhs.net", "clinical-safety-officer@nhs.net"]
}

GET/api/v1/tenant/governance/decisions

List all enforcement decisions (the audit trail of what was enforced, when, and why).

Decision RecordJSON

{
  "data": [
    {
      "id": "dec-uuid",
      "signalId": "fin-alert-001",
      "policyId": "pol-uuid",
      "action": "throttle",
      "scope": { "scopeType": "agent", "scopeIds": ["clinical-summariser-prod"] },
      "priority": 100,
      "appliedAt": "2026-08-13T10:00:01Z",
      "revertedAt": null,
      "traceId": "trace-uuid"
    }
  ]
}

Conflict Resolution

When multiple signals target the same subject with different enforcement actions, AuthHub resolves conflicts using priority ordering. Higher priority wins. Conflicts are logged for audit.

GET/api/v1/tenant/governance/signals/conflicts

List all conflicts (current and historical).

Conflict ResponseJSON

{
  "data": [
    {
      "subjectId": "clinical-summariser-prod",
      "competingSignals": [
        { "signalId": "fin-alert-001", "action": "throttle", "priority": 100 },
        { "signalId": "compliance-alert-003", "action": "suspend", "priority": 200 }
      ],
      "winner": { "signalId": "compliance-alert-003", "action": "suspend", "priority": 200 },
      "reason": "Higher priority policy wins (compliance > budget)",
      "resolvedAt": "2026-08-13T10:00:02Z"
    }
  ]
}

Priority guidelines: Compliance and safety signals (200+) always outrank budget signals (100). Custom policies can set any priority. The supersedes field in a policy can explicitly declare which other policies it overrules regardless of numeric priority.

Telemetry & Usage Ingestion

AI Gateways push aggregated usage metrics to AuthHub for real-time dashboards and threshold evaluation. AuthHub does NOT perform financial amortization — that stays in your FinOps platform. This data powers governance state only.

POST/api/v1/tenant/telemetry/usage/batch

Push aggregated usage metrics from AI Gateways. High throughput: up to 10,000 records per request.

Request BodyJSON

{
  "records": [
    {
      "subjectId": "dr-chen",
      "agentId": "clinical-summariser-prod",
      "modelId": "gpt-4o",
      "toolId": "mcp-fhir-server",
      "tokenCount": 4250,
      "computeMs": 1200,
      "estimatedCost": 0.0425,
      "costCentreId": "CC-4200",
      "timestamp": "2026-08-13T10:15:00Z"
    }
  ]
}

GET/api/v1/tenant/telemetry/usage/by-subject

Usage aggregation by subject. Supports time range and granularity filters.

GET/api/v1/tenant/telemetry/usage/by-model

Usage aggregation by model (GPT-4o, Claude, etc.).

GET/api/v1/tenant/telemetry/usage/by-tool

Usage aggregation by MCP tool / external API.

GET/api/v1/tenant/telemetry/usage/by-cost-centre

Usage aggregation by cost centre (maps to FR-3.1 dashboard requirement).

Query Parameterstext

?from=2026-08-01&to=2026-08-13    Time range (required)
?granularity=daily                  hourly | daily | weekly | monthly
?costCentreId=CC-4200               Filter by cost centre (optional)
?limit=100&cursor=...               Pagination

Shadow mode: When configured, AuthHub compares telemetry-derived cost estimates against FinOps billing signals. Drift exceeding 10% emits a telemetry_billing_drift alert — catching metering discrepancies before they become invoice surprises.

Agentic & Tool Governance

Governance enforcement extends beyond LLM access to the tools agents use — MCP servers, external APIs, and delegated sub-agents. When a contract expires for a data provider, the agent loses access to that specific tool without losing base model access.

Tool Registry

POST/api/v1/tenant/governance/tool-registry

GET/api/v1/tenant/governance/tool-registry

List all registered tools with approval status.

{
  "toolId": "mcp-bloomberg-data",
  "name": "Bloomberg Market Data (MCP)",
  "type": "mcp_server",
  "vendor": "Bloomberg LP",
  "contractId": "contract-bloomberg-2026",
  "costCentreId": "CC-4200",
  "approvedAgents": ["market-analyst-agent", "risk-calculator-v2"],
  "monthlyAllowance": 500.00,
  "currency": "GBP"
}

Transitive Enforcement

When a governance signal suspends or throttles a subject, the enforcement cascades through the delegation chain automatically:

Cascade Exampletext

Signal: budget_exceeded (critical) → subject: dr-chen

Enforcement cascade:
  dr-chen [SUSPENDED]
    → clinical-summariser-prod (delegated agent) [SUSPENDED]
      → mcp-fhir-server (tool session) [TERMINATED]
      → mcp-terminology-lookup (tool session) [TERMINATED]
    → discharge-bot-v2 (delegated agent) [SUSPENDED]
      → mcp-letter-generator (tool session) [TERMINATED]

Depth limit: 3 hops (configurable per tenant)

Tool-Level Targeting

Signal policies can target specific tools without affecting base model access:

Policy targeting a specific toolJSON

{
  "name": "Bloomberg contract expired",
  "signalType": "contract_status_changed",
  "celCondition": "payload.vendorId == 'bloomberg-lp' && payload.newStatus == 'expired'",
  "enforcementAction": "suspend",
  "affectedScopeSelector": {
    "scopeType": "tool",
    "scopeIds": ["mcp-bloomberg-data"]
  },
  "priority": 300
}

Shadow tool detection: If an agent invokes an unregistered MCP server, AuthHub accepts an unapproved_tool_invocation signal from the AI gateway and appliesaudit_only or suspend per tenant policy.

Circuit Breakers & Safety

Governance automation that can shut things down must itself be protected from failure. Circuit breakers prevent external system glitches from causing enterprise-wide AI outages.

Global Governance Pause

POST/api/v1/tenant/governance/pause

Instantly suspend ALL automated governance enforcement. Requires tenant_admin role. Re-enablement requires dual-admin approval.

Request BodyJSON

{
  "reason": "Suspected false positive cascade from FinOps integration",
  "requestedBy": "platform-admin@nhs.net",
  "maxDurationHours": 4
}

Response (200)JSON

{
  "pauseId": "pause-uuid",
  "status": "active",
  "enforcementsPaused": 12,
  "expiresAt": "2026-08-13T18:00:00Z",
  "resumeRequires": "dual_admin_approval"
}

POST/api/v1/tenant/governance/resume

Resume governance enforcement after a pause. Requires dual-admin approval.

Source Circuit Breaker

Automatic protection: if a source sends >20% malformed signals within 5 minutes, its circuit breaker trips and all new signals from that source are quarantined until manual reset or auto-cooldown.

Trigger	Action	Recovery
>20% schema failures in 5min	Quarantine all signals from source	Auto-reset after 10min cooldown
10x normal volume in 5min	Quarantine new signals, alert admins	Manual approval required
>100 enforcement changes/min	Queue with 30s delay	Auto-drains when rate normalises

Fail-Open / Fail-Closed

Configurable per signal severity — what happens when the governance PDP cache is unreachable:

Severity	Default Behaviour	Rationale
info / warning	Fail-open (allow)	Availability over governance for non-critical signals
critical / security	Fail-closed (deny)	Compliance over availability for high-risk signals

Tenants can override these defaults per signal type via POST /api/v1/tenant/governance/signal-policieswith the failBehaviour field.