Security

Authentication, authorization, token and credential handling, transport security and data protection.

Authentication

The API uses JWT bearer tokens. Obtain a token via POST /v1/onboarding/login/user and send it on protected calls:

Authorization: Bearer <JWT_TOKEN>

Tokens are JWTs and carry an expiry (exp) claim — observed lifetimes in the source vary; the canonical TTL is To be confirmed.
Refresh near expiry via POST /v1/onboarding/auth/refresh rather than re-prompting for credentials.
Optional MFA (TOTP) and email OTP add a second factor — see Authentication, MFA & OTP.
SSO is supported via the OAuth2-style POST /v1/onboarding/token endpoint.

Authorization (RBAC)

Access is governed by role-based access control. A user holds a role; a role grants module/sub-module actions. A 403 indicates the authenticated principal lacks the required action. Model least-privilege roles and verify entitlements via GET /v1/onboarding/me. See Users, Roles & Modules.

Token handling

⚠️ Warning

Treat access tokens as secrets. Do not commit them to source control, embed them in shared Postman collections, log them, or place them in URLs.

Store tokens in memory or a secure store; avoid localStorage for long-lived tokens in browser contexts.
Scope tokens to the shortest practical lifetime and refresh rather than reuse indefinitely.
On logout (POST /v1/onboarding/logout), discard the token client-side.
Rotate immediately if a token may have been exposed.

TLS / SSL expectations

All non-local traffic must use HTTPS (TLS). Observed responses include strong transport-security headers, e.g.:

Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Content-Security-Policy: default-src 'self'; ...
Referrer-Policy: strict-origin-when-cross-origin

Validate server certificates; never disable certificate verification in clients.
Use TLS 1.2+ (minimum version To be confirmed with the platform team).

Sensitive data handling

Several fields are sensitive and must be protected end-to-end:

Data	Where it appears	Guidance
Login email / password	`login/user`, `users/password`, `mfa/status`	Transmitted as encrypted strings; never send plaintext.
MFA secret	`mfa/status`, `mfa/register` (`encodedSecret`)	Never log or persist beyond enrolment.
Core-banking credentials	`core-connectivity` (`userName`, `password`, `adminPassword`)	Send over TLS only; store in a secrets manager.
Terminal/app keys	`terminal-key` (`appKey`)	Treat as secret; rotate on suspicion of exposure.
Access tokens / API keys	`Authorization` header; external mail keys	Never embed in code, collections, or URLs.

❗ Important

This documentation deliberately replaces all real secrets from the source material with placeholders and synthetic values. Apply the same discipline in your own examples, tickets and screenshots.

Rate limiting

Rate-limiting policy is typically enforced at the API gateway. The specific limits, headers (e.g. Retry-After) and the 429 behaviour are To be confirmed. Build clients to back off exponentially with jitter on 429 and 503.

Operational endpoints

Spring Actuator and metrics endpoints (/actuator/*) can expose sensitive operational data (heap dumps, beans, thread dumps). These should be network-restricted and not exposed publicly. See the Operational & Monitoring appendix.