Node API
Node API
One HTTP contract for driving and auditing operations on a running node, separate from the product SDKs. It is the boundary between the service surface — operators, control-plane services, support tooling, and audit exporters — and the secret-dependent execution layer inside the node.
A client of this API already knows the domain manifest, policy authority material, operation id, session id, key id, epoch, request digest, and call context. The node enforces local admission, durable replay, policy-receipt materialization, publication gating, and external-export binding.
Why a separate node API
The node API sits below Hero, Expert, and the mobile SDKs. Those are product surfaces that compose intents; this is the contract a node operator, a control-plane service, or an audit exporter speaks to a running node.
- Canonical operations — it accepts canonical operation admission objects and returns ledger roots, journal roots, retained records, lifecycle projections, and secret-kernel gate receipts.
- Verifiable public state — every accepted mutation records roots, so replay, support, and audit tools reconstruct the same state independently.
- One contract across deployments — the same surface backs an on-prem cluster, a SaaS-hosted node, and hybrid splits.
- Governance surface — it admits operations, gates publication, and exposes evidence; secret-dependent execution stays behind the paired secret kernel.
What you drive through it
The surface has three groups. Driving an operation walks the governance group end to end; Endpoints is the full reference.
- Governance — submit operations, apply admission decisions, materialize policy receipts, start execution, gate publication, bind external rails.
- Reads — operation record, lifecycle projection, evidence bundle, scoped audit replay, admission ledger, and journal; side-effect free.
- Operator — liveness, readiness, Prometheus metrics, and runtime interface version.
Two API layers
A deployment exposes two HTTP layers. The runtime node API on this page (default bind 0.0.0.0:9100) is the low-level protocol contract of one node: canonical admission objects, bind contexts, and roots. The operation gateway (default bind 0.0.0.0:9200) is the authenticated product facade above it: POST /v1/operations/sign, approval collection (…/approve), orchestrated …/execute and …/publish, custody key lifecycle (/v1/custody/keys/{key_ref} with sign, refresh, reshare, rotate, recover), and POST /v1/policy/preview for evaluation without execution.
The gateway authenticates callers — modes: disabled, trusted_headers (x-client-id, x-subject-id, x-roles, x-scopes, x-tenant), jwks, and introspection against an OIDC provider — collects approvals to quorum, obtains the signed AdmissionDecision from the Policy Authority, and drives the runtime node steps below. Control-plane services integrate against the gateway; the runtime node API is the contract for node operators, cluster tooling, and audit exporters.