API Reference
Layer-7 Governance Interfaces
This API exposes the Layer-7 governance loop as infrastructure:
evaluate actions, score risk, route authority approvals, write decisions to a ledger, and enforce allow/deny outcomes.
The design assumes default deny if governance cannot complete.
Contract: the enforcement gateway must not execute an action unless the decision is authorized and the ledger write is confirmed.
Base URL & Conventions
Versioned paths are required. Responses are JSON. All requests must include an idempotency key for safe retries.
Base URL: https://api.corevexa.com
API Version: /v1
Content-Type: application/json
Idempotency: Idempotency-Key: <uuid>
Idempotency is required because a governance decision may be evaluated multiple times due to retries, timeouts, or downstream dependency failures.
Authentication
Corevexa supports multiple auth modes depending on environment. Choose one and lock it per deployment.
Production deployments should prefer signed identities (JWT) or mutual TLS (mTLS).
Option A — API Key (starter)
Fast to implement. Best for controlled internal prototypes. Rotate keys and scope by environment.
Option B — JWT (recommended)
Role-bearing identities. Enables granular authority checks and signed approval submissions.
Header: Authorization: Bearer <jwt>
Option C — mTLS (high assurance)
Strong client identity at the transport layer. Common for regulated and high-trust environments.
Mechanism: client certificate + CA chain
Authority model tie-in
Auth identifies the actor; authority rules determine what that actor can approve, override, or execute.
# Example (API key)
curl -X GET “https://api.corevexa.com/v1/health” \
-H “Authorization: Bearer YOUR_API_KEY”
Endpoints (v1)
These endpoints support the full governance loop. Minimal MVP uses: evaluate → approvals (if needed) → ledger retrieval → enforce.
| Method |
Path |
Purpose |
| GET Health |
/v1/health |
Service status + version metadata |
| POST Evaluate |
/v1/evaluate |
Create a decision: normalize action → score risk → compute authority requirements |
| GET Decision |
/v1/decisions/{decision_id} |
Fetch decision object + approval state + enforcement result |
| POST Approve |
/v1/approvals |
Submit an approval signature against a decision |
| POST Override |
/v1/overrides |
Submit an explicit override (requires elevated authority, always logged) |
| GET Ledger |
/v1/ledger |
Query immutable decision records by filters (time, actor, risk band, outcome) |
Minimal integration: you can run governance with just POST /evaluate and GET /decisions/{id}.
Approvals and overrides become necessary once you enforce real authority routing.
POST /v1/evaluate
Submits a proposed action. Corevexa normalizes it into a decision object, applies risk scoring, and returns the authority requirements.
Execution must not occur until the returned decision is authorized and logged.
curl -X POST “https://api.corevexa.com/v1/evaluate” \
-H “Authorization: Bearer <token>” \
-H “Content-Type: application/json” \
-H “Idempotency-Key: 7b56c7d7-3f50-4c4e-a21b-8d6f9d8d2a8f” \
-d ‘{
“action”: {
“class”: “transfer_funds”,
“intent”: “Pay vendor invoice #8831”,
“target”: { “type”: “bank_account”, “id”: “acct_2291” },
“payload”: { “amount_usd”: 1250, “vendor_id”: “vendor_51” }
},
“context”: {
“actor”: { “id”: “user_17”, “role”: “finance_ops” },
“environment”: “production”,
“request_source”: “app.corevexa.com”,
“trace”: { “correlation_id”: “corr_9f21” }
},
“policy_version”: “v1.0”
}’
Response (example)
{
“decision_id”: “dec_01JAB8Q2W0T7Q2K9Y9N0YB6KQF”,
“status”: “pending_authority”,
“policy_version”: “v1.0”,
“risk”: {
“band”: “high”,
“score”: 0.82,
“reasons”: [“monetary_action”, “production_environment”, “vendor_payment”]
},
“authority”: {
“required”: [
{ “role”: “finance_manager”, “min_signatures”: 1 },
{ “role”: “security_officer”, “min_signatures”: 1 }
],
“satisfied”: false
},
“enforcement”: {
“default”: “deny”,
“allow_if”: [“authority_satisfied”, “ledger_confirmed”]
},
“ledger”: { “write_state”: “pending” },
“timestamps”: { “created_at”: “2026-02-24T18:32:11Z” }
}
If authority.satisfied is false, the correct downstream behavior is deny/queue until approvals arrive.
POST /v1/approvals
Submits an approval signature for a decision. Approvals should be cryptographically verifiable in production (JWT claims or signed payloads).
curl -X POST “https://api.corevexa.com/v1/approvals” \
-H “Authorization: Bearer <token>” \
-H “Content-Type: application/json” \
-H “Idempotency-Key: 2a6f6f64-9f6a-4c3d-8fb2-83f3d9a1f0a5” \
-d ‘{
“decision_id”: “dec_01JAB8Q2W0T7Q2K9Y9N0YB6KQF”,
“approval”: {
“actor”: { “id”: “user_88”, “role”: “finance_manager” },
“intent”: “Approve vendor payment #8831”,
“method”: “jwt”,
“signature_ref”: “sig_aa91”
}
}’
Response (example)
{
“decision_id”: “dec_01JAB8Q2W0T7Q2K9Y9N0YB6KQF”,
“status”: “pending_authority”,
“authority”: {
“required”: [
{ “role”: “finance_manager”, “min_signatures”: 1 },
{ “role”: “security_officer”, “min_signatures”: 1 }
],
“received”: [
{ “role”: “finance_manager”, “actor_id”: “user_88”, “at”: “2026-02-24T18:36:01Z” }
],
“satisfied”: false
}
}
GET /v1/decisions/{decision_id}
Retrieves the current state of a decision, including authority satisfaction, ledger finality, and enforcement outcome.
curl -X GET “https://api.corevexa.com/v1/decisions/dec_01JAB8Q2W0T7Q2K9Y9N0YB6KQF” \
-H “Authorization: Bearer <token>”
{
“decision_id”: “dec_01JAB8Q2W0T7Q2K9Y9N0YB6KQF”,
“status”: “authorized”,
“risk”: { “band”: “high”, “score”: 0.82 },
“authority”: { “satisfied”: true },
“ledger”: { “write_state”: “confirmed”, “record_id”: “ldr_01JAB8R5QZ9…” },
“enforcement”: { “result”: “allow” }
}
Gateway rule: allow only when authority.satisfied=true AND ledger.write_state=confirmed.
GET /v1/ledger
Queries the immutable ledger of decisions. Use this for audits, reporting, incident reconstruction, and governance drift detection.
curl -X GET “https://api.corevexa.com/v1/ledger?from=2026-02-01T00:00:00Z&to=2026-02-24T23:59:59Z&risk_band=high&outcome=allow” \
-H “Authorization: Bearer <token>”
Ledger queries should be read-only and never mutate the underlying record. Append-only is the default posture.
Schemas (v1)
This is the minimum decision envelope used across endpoints. It is intentionally explicit and audit-friendly.
{
“decision_id”: “dec_*”,
“policy_version”: “v1.0”,
“action”: {
“class”: “string”,
“intent”: “string”,
“target”: { “type”: “string”, “id”: “string” },
“payload”: { }
},
“context”: {
“actor”: { “id”: “string”, “role”: “string” },
“environment”: “dev|staging|production”,
“request_source”: “string”,
“trace”: { “correlation_id”: “string” }
},
“risk”: { “band”: “low|medium|high|critical”, “score”: 0.0, “reasons”: [] },
“authority”: {
“required”: [{ “role”: “string”, “min_signatures”: 1 }],
“received”: [{ “role”: “string”, “actor_id”: “string”, “at”: “ISO-8601” }],
“satisfied”: false
},
“ledger”: { “write_state”: “pending|confirmed|failed”, “record_id”: “string|null” },
“enforcement”: { “default”: “deny”, “result”: “deny|allow|queue|escalate” },
“timestamps”: { “created_at”: “ISO-8601” }
}
Policy versions must be pinned per decision. Never “reinterpret” old decisions under new policies. That breaks audit integrity.
Error Model
Errors use a standard envelope. Do not leak sensitive policy internals. Return enough to diagnose while keeping governance safe.
{
“error”: {
“code”: “AUTH_INSUFFICIENT”,
“message”: “Actor role cannot approve this decision.”,
“details”: {
“decision_id”: “dec_*”,
“required_roles”: [“finance_manager”,”security_officer”]
}
}
}
| Code |
Meaning |
Typical Fix |
| AUTH_REQUIRED |
Missing or invalid auth credentials |
Provide token/cert, verify audience + expiry |
| AUTH_INSUFFICIENT |
Actor lacks required authority |
Route to correct role / multi-sig |
| POLICY_VERSION_INVALID |
Policy bundle not found / not allowed |
Use a valid pinned policy version |
| IDEMPOTENCY_CONFLICT |
Key reused with different payload |
Generate a new idempotency key |
| LEDGER_WRITE_FAILED |
Decision could not be finalized |
Deny execution; retry ledger write safely |
Non-negotiable: if ledger write fails, execution must not proceed—even if approvals are complete.