A12 - Approval Workflow

Group	Technology	Status	Service	Roadmap phase	Contracts
A - Governance, identity and security	PostgreSQL + API (optional Temporal adapter)	to develop	approvals	3	audit-event

Back to index - Français

Role and responsibilities

Durable approval requests with separation of duties for promotions, sensitive tools and exceptions.

Data model

Tables (schema eai, every tenant table carries tenant_id uuid NOT NULL with an RLS policy on current_setting('app.tenant_id', true)::uuid): eai.approvals, eai.audit_events.

API endpoints

• GET /v1/approvals
• POST /v1/approvals
• GET /v1/approvals/{id}
• POST /v1/approvals/{id}/decide

POST /v1/approvals HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: en
Content-Type: application/json

{"action": "deploy", "resource_type": "agent", "resource_id": "invoice-agent", "reason": "Promote version 1.4.0 to production", "approver_roles": ["security_officer"], "quorum": 1}

{
  "id": "a1ab0542-301d-4eef-a8be-64d5173ad21e",
  "requester": "alice",
  "action": "deploy",
  "resource_type": "agent",
  "resource_id": "invoice-agent",
  "run_id": null,
  "reason": "Promote version 1.4.0 to production",
  "payload": {},
  "quorum": 1,
  "approver_roles": ["security_officer"],
  "status": "pending",
  "expires_at": "2026-10-31T01:35:52.793643Z",
  "decided_at": null,
  "created_at": "2026-10-30T01:35:52.792996Z",
  "updated_at": "2026-10-30T01:35:52.792996Z",
  "decisions": [],
  "approvals_count": 0
}

Errors use the common envelope {"error": {"code", "message", "message_i18n", "details", "request_id"}}; lists are paginated with limit and cursor.

Controlled promotions

Moving a model, tool or agent to approved or active opens an approval (action: promotion, approver roles tenant_admin and security_officer) and answers 202 with approval_id. The requester cannot approve it. On approval: a system classified high risk (latest risk assessment high, or agent risk_level high) needs an approved risk assessment; then the blocking promotion suites of the target run (evaluation.on_promotion); the status is applied only when they pass. The outcome is stored in payload.promotion and audited (promotion.request, promotion.apply, promotion.blocked). Skills (POST /v1/skills/{name}/status) and MCP servers (POST /v1/mcp/servers/{id}/status) answer 202 the same way; plugins become active through install, guarded by the owner relation; a skill can no longer be set to approved outside an approved promotion (409 promotion_requires_approval). Retirements stay immediate and audited. Platform wide models changed by a platform admin without a tenant are not covered, approvals being tenant scoped.

SDK usage

Python (enterprise_ai):

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
items = client.approvals.list()

TypeScript (@enterprise-ai/sdk):

import { EnterpriseAI } from "@enterprise-ai/sdk";

const eai = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const items = await eai.approvals.list();

Java (enterprise-ai-java):

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
var items = client.approvals().list();

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
items, err := client.Approvals.List(ctx)

Configuration

• Environment: EAI_DATABASE_URL, EAI_OTEL_EXPORTER_OTLP_ENDPOINT.
• Helm values: controlPlane.enabled, controlPlane.replicas, controlPlane.resources, controlPlane.config.

Security controls

• Authentication by OIDC JWT, tenant API key with scopes, or SPIFFE mTLS; tenant resolved from the credential, never from the body.
• Authorization through OpenFGA and OPA decisions; every mutation and decision writes a hash-chained eai.audit_events row.
• Secrets never returned by the API; TLS everywhere; Cilium network policies restrict who can reach the service.

Separation of duties: the requester cannot approve its own request (409 separation_of_duties).

Observability

• Metrics: eai_approval_workflow_requests_total, eai_approval_workflow_errors_total, eai_approval_workflow_latency_seconds (Prometheus).
• Traces: OpenTelemetry spans eai.approvals.* with W3C traceparent propagation, AI spans forwarded to Opik.
• Audit actions: approval.request, approval.decide, approval.expire, policy.evaluate.

FinOps aspects

Operating cost is allocated per tenant and project through labels on Usage Events and Kubernetes resource requests; no direct per-call cost.

Failure modes and resilience

• Stateless replicas behind the API Gateway, PostgreSQL HA for state; readiness probe GET /readyz removes unhealthy pods.
• External system unavailable: fail closed for security decisions, explicit error code, no silent bypass.

Standalone adoption (client of a client)

A client of a client can adopt this brick alone with the Python SDK sub-client client.approvals (TS eai.approvals, Java client.approvals(), Go client.Approvals). Minimal deployment: Control Plane API + PostgreSQL + Keycloak (or API keys), the Control Plane loads every domain of services/control-plane/src/eai/domains; the optional chart components are switched off in deploy/helm/enterprise-ai/values.yaml (vllm.enabled, qdrant.enabled, nats.enabled, workers.enabled).

Acceptance tests

1. A tenant cannot read or modify another tenant's resources (RLS test).
2. Every mutation produces an audit event verifiable by GET /v1/audit/verify.
3. Errors are returned in English and French according to Accept-Language.