Skip to main content

Console and internal APIs

Overview​

The AML Fraud Detector exposes a comprehensive REST API documented using SpringDoc OpenAPI 2 (Swagger UI).

  • Swagger UI: http://localhost:2637/api/v1/swagger-ui.html
  • OpenAPI JSON (all groups): http://localhost:2637/api/v1/api-docs
  • Management API OpenAPI: http://localhost:2637/api/v1/api-docs/management
  • Management API docs site: docs-site/ → /management-api (static reference generated from springdoc)

Authentication​

All paths below are relative to the servlet context /api/v1.

CallerMechanism
Console usersSession cookie after POST /api/v1/auth/login (CSRF protection is disabled in SecurityConfig.java; the session cookie is the credential)
PSP back-office jobsPSP API key (X-Api-Key: hka_... or Authorization: Bearer hka_...), accepted only on the machine paths /transactions/ingest* and /transactions/{id}/assessment
Edge NodesmTLS client certificate signed by the Hokeka Edge CA (/edge/**)

Endpoint guards use hasAuthority('<PERMISSION>') with the permission names the Console mirrors in FRONTEND/src/lib/consoleRbac.ts, plus some role-based (hasAnyRole) guards. See CONSOLE_ROLE_MATRIX.md.

Key API Groups​

TagDescriptionBase Path
AuthLogin, invite registration, password reset/auth/**, /auth/password-reset/**
UsersUser & Role Management/users/**
AlertsFraud & AML Alerts/alerts/**
CasesCase Management & Investigation/cases/**, /compliance/cases/**
TransactionsTunnel-backed reads of Edge-held transactions (EdgeTransactionController): list, detail, :batchGet, related, streamed export. POST /transactions/ingest* is the legacy cloud ingest, deprecated until R12 deletes it/transactions/**
Edge machine APICalled by Edge Nodes over mTLS: enrol with CSR, certificate renewal, CA certificate and CRL, rule bundle, metrics, decision records v2, sealed Edge Config, sanctions list, tunnel/edge/**
Edge Nodes (admin)Node approve, reject, suspend, revoke, reinstate, enrolment-code reissue/edge/nodes/**
Edge dataTunnel and ledger status, PSP-visible access log of every pull/edge-data/**
PSP data settingsRetention (5 to 25 years), support access, cross-PSP opt-in, maker-checker changes; Edge Config limits and merchant blocklist; legacy back-fill (R15)/psps/{pspId}/data-retention, /support-access, /cross-psp-opt-in, /data-settings/**, /edge-config/**, /edge-backfill/**
Regulatory filingFile a SAR or CTR from Edge pulls; filed-document register/sar/{id}/file, /ctr/{id}/file, /filed-documents/**
MerchantsFull onboarding, KYC ownership and risk/merchants/**
ScreeningSanctions & PEP Screening/screening/**
ReportsRegulatory & Operational Reports/reports/**
PSPPayment Service Provider Management/psps/**
BillingSaaS Billing & Invoicing/billing/**
ComplianceSAR register and workflow (create, submit, approve, reject), KYC, compliance links, calendar/compliance/**
Regulatory submissionsSubmission register, approve, reject, amend, file/reports/submissions/**
BlacklistPayment blacklist/blacklist/**
Multi-Asset AMLCustomer 360, linked accounts, normalized transactions, risk signals/multi-asset/**
Record TraceabilityPSP-scoped detail graphs, related records, occurrences and report provenance/records/{recordType}/{recordId}
AnalyticsDashboards, Risk Analytics, Metrics/analytics/**
Risk ManagementCountry Risk, High-Risk Countries/risk/**
MonitoringTransaction Monitoring, Reports/monitoring/**
SubscriptionsPSP Subscription & Tier Management/subscriptions/**
PaymentsM-Pesa & Bank Transfer Payments/billing/payments/**
CBK ComplianceCentral Bank of Kenya GDI Reporting/compliance/cbk/**

Cross-PSP fraud intelligence has no public REST group: it is an opt-in setting (/psps/{pspId}/cross-psp-opt-in) and its indicators come from filed SARs only.

Endpoint-level detail (paths, guards, Edge machine endpoints, rate limits) is in features/API_INTEGRATION.md. The residency rules are normative in EDGE_DATA_RESIDENCY_CONTRACT.md; R-package status is in the plan table.

Rate limits​

In the production profile: 100 requests per minute per client IP (plus a burst of 20); 10 per minute per IP on login, invite registration and password reset; PSP API keys 1,200 per minute per key on their machine paths, not counted against the per-IP limit; Edge machine paths are not limited per IP (nginx limits them per client certificate). There are no plan tiers.

Multi-Asset Customer 360​

The multi-asset API is PSP scoped from the authenticated principal. It supports customer creation and search, linked asset accounts, Customer 360 aggregation, and a risk-signal feed. Its transaction ingestion stores transactions in the cloud: it is part of the legacy cloud pipeline that R15 back-fills to the Edge and R12 deletes. See Multi-Asset AML and Customer 360.

Running the Application​

# Development
cd BACKEND
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# Then open:
# http://localhost:2637/api/v1/swagger-ui.html

Production Considerations​

  • In production, Swagger UI can be disabled via: 
    springdoc.api-docs.enabled=false
    springdoc.swagger-ui.enabled=false
  • Or protected behind authentication.

Best Practices​

  • All new endpoints must include:
    • @Tag(name = "...") at class level
    • @Operation(summary = "...", description = "...")
    • @ApiResponse annotations for success and error cases
  • Use meaningful response DTOs instead of raw entities.
  • Document all request/response examples using @ExampleObject.

Current Status​

Full API groups documented. For comprehensive PSP integration guide with authentication, billing, webhooks, and code examples in Python, JavaScript, Java, and cURL, see:

➡️ PSP API Guide

  • BACKEND/src/main/java/com/posgateway/aml/config/OpenApiConfig.java
  • Controllers under controller/ package

Last Updated: 2026-10-18 Owner: Lappie Ya Home (Senior Developer)