Gateway API

Operation gateway

The operation gateway is the authenticated server-to-server REST surface (default bind 0.0.0.0:9200). Custody platforms, treasury backends, and control-plane services integrate against it; it collects approvals, obtains signed admission decisions from the Policy Authority, and drives the runtime node steps below it.

The gateway exposes two operation families: product signing operations under /v1/operations and the custody key lifecycle under /v1/custody. Both return the same view objects — an operation state, intent summary, approval and policy status, runtime references, and next_actions naming the endpoints that advance the operation.

Authentication

Auth mode is deployment configuration: local development can use an auth bypass profile; production deployments use trusted headers behind an authenticating reverse proxy, JWKS bearer-token validation, or token introspection against an OIDC provider.

Scopes gate endpoint groups: operations.* for signing operations, custody.* for the custody family, audit.read for audit-replay exports. Every request that creates or advances an operation carries a client binding object — client id, subject id, roles, scopes, optional tenant, token id, and client-certificate hash — recorded into the operation's evidence.

Signing operation flow

POST /v1/operations/sign submits a payment intent and returns an OperationView. Approvals accumulate through POST /v1/operations/{id}/approve; when the configured quorum is reached, the gateway obtains the signed AdmissionDecision from the Policy Authority and applies it to the runtime. POST /v1/operations/{id}/execute sequences the runtime policy-receipt and execute steps; POST /v1/operations/{id}/publish drives the publication gate. GET /v1/operations/{id} returns the current view at any point.

Sign to publish over the gateway
sh
curl -X POST "$GW/v1/operations/sign" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @sign-request.json          # -> {operation_id, state, next_actions}

curl -X POST "$GW/v1/operations/$OP/approve" \
  --data-binary @approval-evidence.json     # repeat to quorum

curl -X POST "$GW/v1/operations/$OP/execute" -d '{}'
curl -X POST "$GW/v1/operations/$OP/publish" \
  --data-binary '{"scope":"signature","requested_at_ms":1719300000000}'

curl "$GW/v1/operations/$OP"                # state: published

SignOperationRequest

Fields of the sign submission body:

  • idempotency_key — product request id; resubmission returns the existing operation.
  • payment — {from_account, to_account, amount_minor, currency, reference}.
  • key_ref — optional key identifier; bip32 — optional {network, path} derivation.
  • requested_participants — 0-based signer indices; threshold — optional override.
  • publication_mode — manual (explicit publish call) or automatic.
  • epoch_fence_token_hex — optional fence rejecting execution across an epoch change.
  • client — the caller binding recorded into evidence.

OperationView

Every gateway response returns the same view: operation_id; state (submitted, pending_approval, admitted, receipt_materialized, executing, executed, published, failed); intent summary; approvals (approved/required/subjects); policy preview (decision, bundle id and hash, reasons, obligations); runtime references (phase, record root, ledger root, admission hash, policy receipt id, permit binding id, result ref, publication receipt); and next_actions.

Policy preview

POST /v1/policy/preview evaluates a sign request against the active policy bundle without creating an operation: it returns the decision, bundle id and hash, reasons, obligations, and the facts the evaluation consumed. Use it for pre-flight checks in approval UIs and for policy regression tests in CI.

Node API layers below the gatewayGateway HTTP errorsGateway OpenAPI (YAML)