Authentication

Every request to the CBA API requires a JWT bearer token and a tenant identifier. The platform uses RSA-256 signed tokens with role-based access control (RBAC) and fine-grained scopes.

Required Headers

Header	Required	Description
Authorization	Yes	Bearer <JWT_TOKEN>
X-Tenant-ID	Yes	Tenant UUID or code (e.g. demo_bank)
Content-Type	For POST/PUT	application/json
Idempotency-Key	For writes	Unique key to prevent duplicate operations
X-Request-ID	Optional	Correlation ID (auto-generated if omitted)

curl https://api.korastratum.com/api/v1/cba/accounts \
  -H "Authorization: Bearer eyJ0eXAi..." \
  -H "X-Tenant-ID: demo_bank"

Getting Your Credentials

1. Sign up at app.korastratum.com/signup
2. Navigate to Settings → API Keys in the dashboard
3. Copy your API Key and Tenant ID
4. For sandbox access, use your sandbox tenant code (e.g. demo_bank)

Your API key is used to obtain a JWT token. The tenant ID (or tenant code) is included in every request via the X-Tenant-ID header.

JWT Token

Tokens are signed with RSA-256. The payload includes:

{
  "sub": "user-uuid",
  "iss": "cba-platform",
  "aud": "cba-api",
  "tenant_id": "tenant-uuid",
  "roles": ["officer"],
  "scopes": ["accounts:read", "accounts:write", "transactions:write"],
  "branch_id": "001",
  "session_id": "session-uuid",
  "name": "Jane Smith",
  "email": "jane@demobank.com",
  "exp": 1740000000,
  "iat": 1739913600
}

Claim	Description
sub	User ID
tenant_id	Tenant this token is scoped to
roles	RBAC roles (see below)
scopes	Fine-grained OAuth scopes
branch_id	User's branch code
session_id	Session identifier for audit

Access tokens expire after 24 hours. Refresh tokens last 7 days.

Roles

Roles determine what actions a user can perform:

Role	Permissions
viewer	Read-only access to accounts, transactions, and reports
teller	Create journals and process deposits/withdrawals
officer	Approve/post journals, create accounts, initiate transfers
manager	Reverse journals, manage inter-branch transfers, approve standing instructions
admin	Full access — create fiscal periods, manage tenant configuration, close periods

Roles are cumulative — a manager has all officer permissions plus their own.

Scopes

Scopes provide fine-grained control over API access:

Scope	Access
customers:read	View customer profiles
customers:write	Create and update customers
accounts:read	View accounts and balances
accounts:write	Create and manage accounts
transactions:read	View transaction history
transactions:write	Create transfers, deposits, withdrawals
payments:initiate	Initiate payments
payments:authorize	Authorize pending payments
loans:read	View loan applications
loans:write	Create loan applications
loans:approve	Approve/reject loans
gl:read	View GL accounts, journals, reports
gl:write	Create and post journals
audit:read	View audit logs
admin:full	Full administrative access

Middleware Chain

The API gateway processes each request through the following middleware in order:

1. Request ID — Assigns X-Request-ID if missing
2. Security headers — Sets X-Content-Type-Options, X-Frame-Options, etc.
3. Rate limiting — Distributed rate limiting via Redis
4. JWT authentication — Validates token signature, expiry, issuer, audience
5. Token blacklist — Rejects revoked tokens
6. Tenant resolution — Resolves X-Tenant-ID to tenant context
7. Idempotency — Deduplicates write requests by Idempotency-Key

Idempotency

All write endpoints (POST, PUT) support idempotency via the Idempotency-Key header. Sending the same key twice returns the original response without re-executing the operation.

curl -X POST https://api.korastratum.com/api/v1/cba/transfers/internal \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: demo_bank" \
  -H "Idempotency-Key: txn-a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

warning

If you reuse an idempotency key with a different request body, the API returns 409 Conflict with code IDEMPOTENCY_CONFLICT.

Idempotency keys expire after 24 hours.

Next Steps

• Multi-Tenancy — Tenant resolution and database isolation.
• API Reference — Full header and response format reference.
• Error Codes — Authentication error codes.