API overview

There are two API surfaces, and they live in different places. Mixing them up is the most common integration mistake.

Surface	Called by	Runs on	Transport	Reference
Edge API	Your payment/API nodes	The Edge Node inside your estate	TLS 1.3 (optional mutual TLS)	How an evaluation works · PSP API guide
Management API	The Console SPA, your tooling, PSP integrations	Hokeka Control Plane	HTTPS, session cookie or PSP API key	Management API reference

The Edge is the only evaluator. Everything else (alerts, cases, filings, billing, fleet) is a Control Plane concern.

Figure 1 — The call direction. Your API nodes call the Edge over TLS on 8443; the Edge calls the Control Plane outbound on 443 and sends decision records only. The Management API is never called by the Edge to evaluate a transaction.

1. Edge API (the one on your network)

Base URL: https://<edge-host>:8443 — bound to 127.0.0.1 by default; widen it with --bind / --allow-subnet during install.

Method	Path	Purpose
POST	/edge/evaluate	Evaluate one transaction; returns the decision
GET	/edge/status	Health, authorisation state, evaluator (native vs fallback), ledger state
GET	/edge/bundle	Bundle pull (machine, mTLS + sealed envelope)
POST	/edge/metrics	Aggregate metrics upload (machine)

/edge/evaluate is the only call most integrations need. It accepts a transaction (ids, PAN hash, amount in minor units, currency, country, channel, timestamp) and answers with a decision (ALLOW/ALERT/HOLD/BLOCK), the score, the rule ids that fired, and the ledger record id.

curl -k https://127.0.0.1:8443/edge/evaluate \
  -H 'Content-Type: application/json' \
  -d '{"txnId":"t-1","panHash":"00…","amountMinor":12500,"currency":"KES","country":"KE","channel":"CARD_PRESENT","timestamp":"2026-01-01T10:00:00Z"}'

Fail-closed: an unapproved node, an unwritable ledger or a suspended licence answers HOLD. Handle HOLD as "do not authorise until resolved", and read /edge/status for the reason.

2. Management API (Hokeka control plane)

Base URL: https://<control-plane>/api/v1. The interactive Swagger UI is served by the running Control Plane at /swagger-ui.html; the OpenAPI document is checked in and rendered here as the Management API reference.

Authentication

Caller	Credential
Console user	Secure, HttpOnly, SameSite=Strict session cookie set at sign-in
PSP machine integration	PSP API key (X-API-Key header) — rate-limited per key
Edge Node (machine paths)	mTLS client certificate issued by the Hokeka Edge CA

A revoked session is detected on the next call (401), and the Console redirects to sign-in.

Authorisation

One permission model, enforced server-side per endpoint and mirrored by FRONTEND/src/lib/consoleRbac.ts. Roles are hierarchical (e.g. MLRO ≥ COMPLIANCE_OFFICER ≥ CASE_MANAGER ≥ INVESTIGATOR); see the role matrix. A 403 means the role lacks the permission — it is not a retryable condition.

Error shape

Edge endpoints answer { "error": "<detail>" }; Control Plane endpoints use the same field where they can, and { "message": "<detail>" } from framework-level failures. Field validation adds fieldErrors ({ "field": "message" }). Treat 4xx as final (show the message), retry only 5xx or network failures.

Pagination

• Offset paging — ?page=0&size=25, answered with content, totalElements, totalPages.
• Cursor paging — the Edge transaction surfaces answer { items, nextCursor, incomplete, unavailableSites, source: 'EDGE' }; the cursor is opaque and the Edge is the source of truth.

3. Which call do I make?

I want to…	Call
Authorise a payment	POST /edge/evaluate on the Edge
Check whether the Edge is healthy	GET /edge/status on the Edge
See an alert or a case	Management API (/alerts, /cases)
File a SAR/STR/CTR	Management API (/compliance/*), then fetch the PDF
Manage the Edge fleet	Management API (/edge/nodes/*)
Read a transaction's detail	Console → tunnel-backed read (Edge is the source)

Related

• PSP API guide — wiring your API nodes, TLS and mutual TLS.
• Console and internal APIs — auth, envelopes, pagination details.
• Data residency contract — what may be sent, and where.