Authentication

Every request to the Digital Banking API requires a JWT bearer token and a tenant identifier. This page covers how to obtain tokens, refresh them, enable two-factor authentication (2FA), and manage sessions.

Required Headers

Header	Description	Example
Authorization	JWT bearer token	Bearer eyJ0eXAi...
X-Tenant-ID	Tenant identifier (UUID or name)	fmfb
Content-Type	Required for POST/PUT bodies	application/json

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

Getting Your Credentials

1. Sign up at app.korastratum.com/signup
2. Navigate to Settings → API Keys in the dashboard
3. Copy your Tenant ID and note your environment (sandbox vs production)
4. Use the login endpoint below to obtain a JWT token

Your tenant ID is also returned in the login response as tenant.id.

Obtaining a Token

POST /api/v1/auth/login

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "deviceInfo": {
    "deviceId": "device-uuid",
    "platform": "ios",
    "osVersion": "17.0",
    "appVersion": "1.0.0"
  }
}

Response:

{
  "success": true,
  "data": {
    "user": {
      "id": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "user",
      "kycStatus": "verified",
      "kycLevel": 3,
      "mfaEnabled": true
    },
    "tokens": {
      "accessToken": "eyJ0eXAi...",
      "refreshToken": "eyJ0eXAi...",
      "expiresIn": 86400,
      "tokenType": "Bearer"
    },
    "tenant": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "fmfb",
      "displayName": "First Microfinance Bank"
    }
  }
}

Token Lifecycle

Property	Value
Algorithm	HS256
Access token TTL	24 hours
Refresh token TTL	7 days
Issuer (iss)	bankapp-api
Audience (aud)	bankapp-client

The JWT payload includes:

{
  "userId": "uuid",
  "email": "user@example.com",
  "tenantId": "uuid",
  "role": "user",
  "permissions": ["transfer", "bill_payment"],
  "mfaEnabled": true,
  "kycStatus": "verified",
  "kycLevel": 3,
  "iat": 1740000000,
  "exp": 1740086400
}

Refreshing Tokens

When the access token expires, use the refresh token to obtain a new pair without re-authenticating.

POST /api/v1/auth/refresh

{
  "refreshToken": "eyJ0eXAi..."
}

Response: Same shape as login — a new accessToken and refreshToken.

warning

Each refresh token is single-use. Store the new refresh token returned by this endpoint and discard the old one.

Two-Factor Authentication (2FA)

The platform supports TOTP (Time-based One-Time Password) with a 30-second window.

Check 2FA Status

POST /api/v1/auth/2fa/status

Enable 2FA

POST /api/v1/auth/2fa/setup

Returns a secret (Base32-encoded) and a qrCodeUrl for authenticator apps.

Verify 2FA Setup

POST /api/v1/auth/2fa/verify-setup

{
  "token": "123456"
}

After verification, subsequent logins will require a TOTP code.

Session Management

Users can have up to 5 concurrent sessions. Sessions expire after 30 minutes of inactivity.

List Sessions

GET /api/v1/auth/sessions

{
  "success": true,
  "data": [
    {
      "id": "sess_abc123",
      "deviceInfo": { "platform": "ios", "appVersion": "1.0.0" },
      "ipAddress": "102.89.xx.xx",
      "lastActive": "2026-02-27T14:00:00Z",
      "current": true
    }
  ]
}

Revoke a Session

DELETE /api/v1/auth/sessions/:id

Logout All Devices

POST /api/v1/auth/logout-all

Password Requirements

Passwords must meet all of the following:

• Minimum 8 characters
• At least 1 uppercase letter
• At least 1 lowercase letter
• At least 1 number
• At least 1 special character (@$!%*?&)

After 5 failed login attempts, the account is locked for 15 minutes.

Password Reset

POST /api/v1/registration/forgot-password

{ "email": "user@example.com" }

The user receives a reset link. Complete the flow with:

POST /api/v1/registration/reset-password

{
  "token": "reset-token-from-email",
  "newPassword": "NewSecurePass456!"
}

Next Steps

• Multi-Tenancy — How tenant detection and isolation work.
• Server Integration — Add auth middleware to your backend.
• Rate Limits — Authentication endpoint limits.