Kumusoft Solutions
EFRIS APIAuth Service
EFRIS APIAuth Service
  1. Auth Service
  • User login
  1. Auth Service

User login

Kumusoft Auth Service – Developer Login guide#

This document provides a concise overview of the Kumusoft authentication flow using
Username/Password + OTP, followed by JWT verification via JWKS.

Authentication Overview#

The authentication process is executed in three controlled phases:
1.
Primary authentication (identifier + password)
2.
Secondary authentication (One-Time Password)
3.
Authorization via JWT verification (RS256 + JWKS)
This approach ensures strong security, stateless APIs, and full auditability.

Step 1: Login (Identifier + Password)#

Request#

{
  "identifier": "user_8742@example.com",
  "password": "P@ssw0rd!92X",
  "tagId": "ZED_INVESTA_MEMBER_PORTAL"
}

Key Points#

identifier may be an email, username, or phone number.
tagId identifies the consuming application/module.
No tokens are issued at this stage.

Response (OTP Challenge Issued)#

{
  "status": {
    "returnCode": "00",
    "returnMessage": "Login successful, OTP sent"
  },
  "data": {
    "name": "John Doe",
    "userId": "9c2a1f7e-31b6-4c92-9e1d-22d6c3b1a901",
    "challengeId": "f3a9c21e-91c8-4e2d-b6a7-77a9f92d5e44",
    "requires2FA": true
  }
}

Step 2: OTP Verification#

Request#

{
  "userId": "9c2a1f7e-31b6-4c92-9e1d-22d6c3b1a901",
  "otp": "728194",
  "challengeId": "f3a9c21e-91c8-4e2d-b6a7-77a9f92d5e44"
}

Response (Authentication Complete)#

{
  "status": {
    "returnCode": "00",
    "returnMessage": "OTP verified successfully"
  },
  "data": {
    "accessToken": "JWT_ACCESS_TOKEN",
    "refreshToken": "REFRESH_TOKEN",
    "expiresIn": 3600,
    "user": {
      "id": "9c2a1f7e-31b6-4c92-9e1d-22d6c3b1a901"
    }
  }
}

Step 3: JWT Verification Using JWKS#

Access tokens are signed JWTs (RS256) and must be verified, not decrypted.

JWKS Endpoint#

https://auth.kumusoft.com/.well-known/jwks.json

JWT Verification Checklist#

Validate signature using JWKS public key
Validate exp (expiration)
Validate iss = https://auth.kumusoft.com
Validate aud = kumusoft:<TAG_ID>

Using the Access Token#

Authorization: Bearer <accessToken>
APIs rely solely on verified JWT claims for authorization and auditing.

Summary#

Passwords authenticate
OTPs confirm intent
JWTs authorize
JWKS guarantees trust
This design enables secure, scalable, stateless authentication across Kumusoft platforms.
Built with