Documentation
Documentation
Comprehensive guides and reference material to help you integrate Korastratum into your application.
Comprehensive guides and reference material to help you integrate Korastratum into your application.
Go from zero to your first API call in 10 minutes. Authenticate, create a customer, and run a KYC verification.
JWT-based authentication with tenant isolation. Learn how to obtain tokens, refresh sessions, and handle multi-tenant access.
Receive real-time notifications for transaction events, KYC status changes, compliance alerts, and more.
Standardized error codes, retry strategies, and idempotency keys to build resilient integrations.
mTLS for service-to-service calls, token blacklisting, rate limiting, and step-up authentication for sensitive operations.
Cursor-based and offset-based pagination, query filtering, and sorting across all list endpoints.
How tenant isolation works across the platform. Row-level security, tenant headers, and data partitioning.
Every API request requires a valid JWT token and a tenant identifier. The platform supports token refresh, blacklisting, and step-up authentication for sensitive operations.
Authorization: Bearer <jwt_token> X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000 X-Request-ID: req-unique-id # Auto-generated if omitted Idempotency-Key: idem-12345 # Required for writes
/api/v1/auth/loginAuthenticate and get JWT + refresh token/api/v1/auth/refreshExchange refresh token for new access token/api/v1/auth/logoutRevoke a specific refresh token/api/v1/auth/logout-allRevoke all tokens for the userRegister webhook endpoints to receive real-time notifications when events occur across the platform. All payloads are signed for verification.
customer.createdNew customer registeredcustomer.kyc.verifiedKYC verification completedtransaction.completedTransaction settled successfullytransaction.failedTransaction failed or reversedscreening.flaggedEntity flagged during compliance screeningalert.createdNew fraud or compliance alert raisedcard.activatedCard activated by customerbill.payment.processedBill payment settledAll errors follow a consistent JSON format with machine-readable codes. Use idempotency keys on write operations to safely retry failed requests.
{
"error": {
"code": "VALIDATION_ERROR",
"message": "The 'email' field is required",
"details": {
"field": "email",
"constraint": "required"
}
}
}VALIDATION_ERRORRequest body or params failed validationUNAUTHORIZEDMissing or invalid JWT tokenFORBIDDENToken valid but insufficient permissionsNOT_FOUNDResource does not exist in this tenantCONFLICTDuplicate resource or idempotency conflictRATE_LIMITEDToo many requests — check X-RateLimit headersINTERNAL_ERRORUnexpected server error — safe to retryAll list endpoints support both cursor-based pagination (for real-time data) and offset pagination (for admin dashboards). Cursor pagination is recommended for production use.
GET /api/v1/customers?limit=20&cursor=eyJ0cyI6MTcwNz...
{
"data": [ ... ],
"pagination": {
"total": 1542,
"limit": 20,
"cursor": "eyJ0cyI6MTcwNzY..."
}
}Default limits are per-minute per tenant. Sensitive routes (/transfers: 30/min, /transactions: 50/min, /loans: 20/min) have stricter limits. Check X-RateLimit-Remaining and X-RateLimit-Reset headers.
Include an Idempotency-Key header on all write requests (transfers, transactions, journals, loans). The gateway caches responses for 24 hours — retrying with the same key returns the original response.
The gateway automatically requires step-up authentication for high-risk operations. Your integration should handle 403 responses with a step_up_required code by prompting the user for additional verification.
For backend integrations, enable mutual TLS authentication. Certificates can be managed through GCP Secret Manager or provided directly.
Every request is scoped to a tenant via the X-Tenant-ID header. Row-level security in the database ensures complete data isolation. Tenant context flows through the entire request lifecycle — from the API gateway through every microservice.
Follow our quickstart guide to make your first API call in under 10 minutes. Or explore the full API reference.