API Reference

The Kora CBA API is a RESTful JSON API served over HTTPS. All services are accessed through a single API gateway.

Base URL

Environment	Base URL
Production	https://api.korastratum.com/api/v1/cba
Sandbox	https://api.korastratum.com/api/v1/cba

info

Both environments use the same base URL. Your API key prefix determines the environment.

All paths are relative to the base URL. For example, GET /api/v1/accounts means:

GET https://api.korastratum.com/api/v1/cba/accounts

Required Headers

Header	Required	Description
Authorization	Yes	Bearer <JWT_TOKEN>
X-Tenant-ID	Yes	Tenant UUID or code
Content-Type	For POST/PUT	application/json
Idempotency-Key	For writes	Unique key to prevent duplicate operations

Response Format

Success

{
  "id": "resource-uuid",
  "field": "value",
  "created_at": "2026-02-28T10:00:00Z"
}

List endpoints return an array with pagination metadata:

{
  "accounts": [ ... ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0wMi0yOCIsImlkIjoiYWNjdC11dWlkIn0="
}

Error

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid format for field: account_id",
  "details": [
    {
      "field": "account_id",
      "reason": "Expected format: UUID",
      "value": "invalid-id"
    }
  ],
  "request_id": "req-a1b2c3d4",
  "timestamp": "2026-02-28T10:00:00Z",
  "documentation_url": "https://docs.korastratum.com/cba/reference/error-codes"
}

See Error Codes for the full list.

Pagination

List endpoints use cursor-based pagination:

GET /api/v1/accounts?limit=20&cursor=eyJ0IjoiMjAyNi0wMi0yOCJ9

Parameter	Type	Default	Max	Description
limit	integer	50	200	Items per page
cursor	string	—	—	Opaque cursor from next_cursor

Response includes:

Field	Description
has_more	true if more pages exist
next_cursor	Pass as cursor to fetch the next page

note

Cursor-based pagination is more efficient than offset-based for large datasets. Cursors are opaque — do not parse or construct them.

Idempotency

All write endpoints support idempotency. Include a unique Idempotency-Key header:

curl -X POST https://api.korastratum.com/api/v1/cba/transfers/internal \
  -H "Idempotency-Key: txn-a1b2c3d4-e5f6" \
  ...

• Same key + same body → returns the original response (no re-execution)
• Same key + different body → 409 Conflict with code IDEMPOTENCY_CONFLICT
• Keys expire after 24 hours

Rate Limit Headers

Header	Description
X-RateLimit-Limit	Max requests per window
X-RateLimit-Remaining	Requests remaining
X-RateLimit-Reset	Unix timestamp when the window resets

See Rate Limits for per-endpoint quotas.

Request ID

Every response includes an X-Request-ID header. If you send an X-Request-ID in your request, it will be echoed back. Otherwise, one is generated automatically. Include this in support requests for tracing.

Service Routing

The API gateway routes requests to the appropriate microservice:

Path Prefix	Service
/api/v1/accounts, /api/v1/products	Account Service
/api/v1/transfers, /api/v1/transactions	Transaction Service
/api/v1/journals, /api/v1/fiscal-periods, /api/v1/reports	GL Service
/api/v1/customers	Customer Service
/api/v1/loans	Loan Service
/api/v1/cards	Card Service
/api/v1/fraud, /api/v1/screening	Fraud Service
/api/v1/workflows, /api/v1/approvals	Workflow Service
/api/v1/audit	Audit Service

Next Steps

• Quickstart — Make your first API calls.
• Error Codes — Full error reference.
• Rate Limits — Request quotas.