Sections
Section 1
Authentication
Two HMAC schemes are supported: operator-bearer (per-operator API keys) and service-account (parser-side bridge to registry).
AEGIS-HMAC — operator-bearer scheme. Header:
AEGIS-SVC — service-account scheme for parser-to-registry bridge. Header:
Authorization: AEGIS-HMAC operator_id=<id>, ts=<int>, sig=<hex64>. Signature is HMAC-SHA256 over canonical request bytes (timestamp + http_method + path + sha256-hex of canonical-JSON body), keyed by an operator secret derived via HKDF from the master env key. Phase-1 plaintext Bearer <operator_id> is deprecated post Day-16 strict-flip.AEGIS-SVC — service-account scheme for parser-to-registry bridge. Header:
Authorization: AEGIS-SVC ts=<ts>, sig=<hmac>. Loopback-only by default (IP allowlist enforced).
Section 2
Agent Passport
Issue, delegate, verify, and revoke v1.x agent passports. Each passport carries a cryptographic signature, governance payload (5-pillar baseline), and optional capability attestation.
POST
/api/agent/issue/challenge
Request a challenge nonce for proof-of-possession during issuance. Caller signs the challenge with the agent's private key and submits the signature alongside the issuance request.
POST
/api/agent/issue
Issue a v1.0 agent passport signed by the operator's per-customer Ed25519 key. Requires
risk_classification + governance_payload (all 5 pillars true). Optional capability_attestation + delegation_chain. Auto-classifier advisory mode flags declared/recommended mismatch; MANDATORY mode (env-flagged) rejects underdeclares.
POST
/api/agent/delegate
Mint a delegation chain entry from a parent agent to a child agent. Subset cannot exceed parent's current authority bounds. v0.2: Ed25519-signed entries with parent_signature_hex + parent_agent_pubkey_pem, server-side verify before mint.
POST
/api/agent/verify-peer
Agent-to-agent verification protocol. Caller submits another agent's passport; server verifies operator signature + registry status + expiry, returns verdict + TTL-bound peer_verification_token (HMAC-bound; 5min default TTL).
POST
/api/agent/revoke
Revoke an agent passport. Per-operator scoping enforced. Composes with /registry/revoke for cross-host propagation.
Section 3
Runtime Protection
Action enforcement endpoint. Every agent action runs through 15 security layers + signature verification + delegation chain intersection before being allowed.
POST
/api/protect
Core protection endpoint. Runs the action through 15 security layers + parses passport + verifies governance/attestation signatures + applies delegation_chain authority intersection + enforces capability scope. Rejects with
401 + correlation_id in error body for self-diagnosis (see troubleshooting).
GET
/api/protect/health
Liveness probe for the runtime protection service. Public, no auth.
Section 4
Universal Agent Registry
Public-verifiable agent identity registry. Any system can verify whether an agent exists and is active without trusting AiEGIS centrally. Permanent-class records are write-once with immutability triggers at the SQL layer.
GET
/registry/health
Liveness probe for the registry service. Public, no auth.
POST
/registry/register
Register an agent with the universal registry. Called by /api/agent/issue after successful issuance. Records governance_payload_hash + passport_signature_hex + risk_classification + permanence_class.
GET
/registry/verify/{agent_id}
Public verification endpoint. Returns agent status (active/revoked/suspended) + governance_payload_hash. No auth required — any system in the world can verify an agent.
POST
/registry/revoke
Revoke an agent in the registry. Syncs with operator revocations DB.
POST
/registry/agent/update-authority
Update an agent's authority block without re-issuing the passport. Validates operator signature + checks new authority does not exceed risk-classification ceiling. Increments generation_counter; parser picks up new constraints automatically on next action.
GET
/registry/permanent/{agent_id}
Birth-certificate endpoint for permanent-class agents. Returns full audit history (issuance + every authority update + status changes), signed by the registry's Ed25519 key. Permanent records are write-once enforced at the SQL trigger layer.
GET
/registry/pubkey
Returns the registry's Ed25519 public key. Verifiers use this to validate /registry/permanent signatures locally without round-tripping.
GET
/registry/operators
Index of operators with registered agents. Counts only; no PII.
Section 5
Anomaly Observability
Registry-side observability surface for verifier failures, peer-verify failures, and policy decisions. Operators query their own events; cross-operator isolation enforced at the SQL layer.
POST
/registry/anomaly/event
Emit an anomaly event (verifier_fail or peer_verify_fail). Service-account auth (parser sidecar) or operator-bearer. Severity-tiered sampling; 202 fire-and-forget.
GET
/registry/anomaly/my_events
Customer self-diagnosis: query anomaly events scoped to your operator. Supports correlation_id filter, hours window (default 168, max 720), limit (default 50, max 500). Cross-operator leak prevention via SQL filter. See my_events self-diagnosis.
GET
/registry/anomaly
Aggregate anomaly statistics for ops dashboards.
GET
/registry/anomaly/health
Single-call ops snapshot consolidating classifier_version + rate-limit pressure + 24h anomaly distribution + last-event timestamp. Composes with the daily-tick observation window runbook.
GET
/registry/anomaly/alerts
Sliding-window alert engine output for ops. Threshold-tunable per operator.
POST
/registry/anomaly/classify
Manual triage classification of an anomaly event. Updates classification field + writes append-only audit row. Used during the observation window to clear ambiguous 'unknown' rows before Day-16 strict-flip gate query. Manual overrides stamp
classification_version='manual'.
GET
/registry/anomaly/flip_gate
Day-16 strict-flip gate query. Returns counts grouped by classification + flip_recommended boolean per protocol-locked threshold (legitimate ratio >0.99 AND zero unknown/adversarial in window).
Section 6
Governance Framework
Versioned governance framework with formal amendment process. Existing passports stay valid under their issuance-version even after new versions land — backwards compatibility preserved.
GET
/registry/governance/versions
List all governance framework versions. Public endpoint. Returns append-only ledger with current_version pointer.
GET
/registry/governance/version/{version}
Fetch specific governance framework version. Used to determine canonical 5-pillar definitions at the time a given passport was issued. Critical for backwards compatibility.
POST
/registry/governance/amend
Propose a new governance framework amendment. Each amendment supersedes the prior current version and is signed by the registry's Ed25519 key. Backwards-compat: passports issued under v1.0 stay valid under v1.0.
Section 7
Operator Workflow
Operator-facing endpoints for managing classification appeals when MANDATORY mode rejects an underdeclared classification.
POST
/api/operator/appeal-classification
Submit an appeal when the auto-classifier recommends a higher level than the operator declared. Required: justification (16-4096 chars) + appealed_recommendation. Append-only audit log; admin manually reviews and may issue override token.
Composes with: Architecture (15-layer security stack) · Troubleshooting (customer self-diagnosis flows) · OWASP AIVSS Issue #31 (independently reproduced runtime-enforcement methodology).