eAuthenticator

Features by category

Getting started

Introduction

Welcome to our Authentication System integration guide! This document provides step-by-step instructions to help you set up and integrate our secure authentication service into your system. Our solution ensures seamless user verification, enhancing both security and user experience.

The aim is to ensure smooth, efficient, and secure authentication for users, as well as a seamless experience for developers integrating the 2FA flow into their systems.

Integrate

The integration process involves initiating the 2FA workflow, handling the authentication request, and processing the user’s verification through a webview interface.

Step 1. Create authorization credentials

To integrate our 2FA solution, you need to set up an account, configure your application, and obtain the necessary credentials for API access.

Create an account on our platform by visiting the registration page.
Sign in to the Domain Console with your newly created account credentials. The Domain Console is where you will manage your application settings and configure 2FA for your platform.
Create a new application: Click on the “Create Application” button to start setting up your application.
Enter Required Information: Fill in the necessary details such as the application name, ip, and any other required fields.
Obtain API Key: After completing the setup, you will receive an API Key. This key will be used in subsequent steps to communicate with our API and enable 2FA functionality in your application.

Note: Please ensure that you enter the correct IP address for your server when prompted. This is required to pass the whitelist check from our system and ensure secure communication with our API.

Step 2. Update your application

Add 2FA Settings in Your Application
- Navigate to the Security page of your application.
- Build a screen that allows users to enable or disable 2FA.
Generate a QR Code
Generate a QR code containing the TOTP provisioning URI and display it. This allows the user to scan the QR code with an eAuthenticator app to add their account.
QR Code Format
The QR code should encode the following URL format:
otpauth://totp/{issuer}:{user_email}?secret={secret_key}&issuer={issuer}&algorithm=SHA1&digits=6&client_id={client_id}&email={user_email}
- Replace {issuer} with your application name.
- Replace {user_email} with the user’s email address.
- Replace {client_id} with your application’s client ID.
- Replace {secret_key} with the TOTP secret assigned to the user (encoded in Base32 format without padding)
- Replace {algorithm} with hashing algorithm used for TOTP generation: SHA1, SHA256 , or SHA512
Display the QR Code and Guide users to scan the QR Code using eAuthenticator App
- Instruct users to download and install the eAuthenticator app from the Google Play Store or Apple App Store.
- Guide users to:
  - Open the eAuthenticator app and tap the ’+’ icon to add a new account.
  - Scan the QR code displayed on your application.
  - Enter the OTP generated by the eAuthenticator app into the input field on your application.
- Alongside the QR code, display an input field where users can enter the TOTP code generated by the eAuthenticator app.
Verify the OTP
After scanning the QR code, users must enter the OTP generated by eAuthenticator app. Your backend must verify this OTP to enable 2FA for the user.
Notify the Server After Enabling/Disabling 2FA
Once the user enables or disables 2FA, your application must send a request to the authentication server to synchronize the updated 2FA status. This ensures that the server is aware of the user’s current 2FA configuration and can enforce it during authentication attempts.
*It is crucial to handle these requests securely by using the API key provided during the setup process. Ensure that all sensitive data is transmitted over HTTPS to prevent unauthorized access or interception.
- API reference

Step 3. Update Your Application to Support Session Creation

After your application is configured to use 2FA, you need to make sure that it can handle user sessions properly.

Upon successful login, your server must call API to create a sessionfor the user using their email.
This API call will return asession_token, which will be used in subsequent requests.

Securely store the session_token for Authentication Validation

After obtaining the session_token, your portal server should store it securely for at least 5 minutes. This token will be compared with the authentication results received from the eAuthenticator service once the user completes the 2FA authentication. By matching the session token with the 2FA response, your system can ensure that the authentication was completed successfully and verify the user’s identity.

Key Steps:

Create User Session: Upon successful login, call the API to generate a session_token.
Store the session_token: Securely store the session_token for at least 5 minutes to allow time for 2FA completion.
Compare session_token with eAuthenticator results: Once the user completes 2FA, retrieve the stored session_token and compare it with the authentication response from the eAuthenticator service.

By implementing this mechanism, your system ensures that authentication is verified correctly while preventing unauthorized access.

Step 4. Integrate the Authentication Flow

You can integrate the 2FA authentication step in two ways, depending on your needs:

API reference

Get session token
Request Headers
- X-API-Key: API key from the Authenticator console of the application. This key is required for authentication.
Request Body Parameters
Parameter Type Required Description
email string ✅ Yes The email address of the user.
client_id string ✅ Yes Your application’s client ID.
Request Example
curl --location 'https://api-authen.ekyc.com/authen-api/api/v1/session-token' --header 'X-API-Key: abcd' --header 'Content-Type: application/json' --data '{ "email": "[email protected]", "client_id": "84c2ad6c-62eb-4217-8f46-a66852e6fe92" }'
Success Response
{ "code": "SUCCESS", "message": "Success", "data": { "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbXBsb3llZV9pZCI6IjEyMzQiLCJjbGllbnRfaWQiOiI4NGMyYWQ2Yy02MmViLTQyMTctOGY0Ni1hNjY4NTJlNmZlOTIiLCJleHAiOjE3MzY4Mzg0NjIsImlhdCI6MTczNjgzODM0Mn0.1nJtIEalRVxhLoxQLIepHxcK6dsPDwfUsyM1YtAqq58" } }
Case of inactive client – This indicates that your application has been marked as inactive in the Domain Console
{ "code": "INACTIVE", "message": "client not active", "data": null }
Error Response
{ "code": "INVALID_REQUEST", "message": "get session token failed", "data": "" }
Get secret number
Request Headers
- X-API-Key: API key from the Authenticator console of the application. This key is required for authentication.
- X-Session-Token: A unique token generated during the session creation process
Request Example
curl --location 'https://api-authen.ekyc.com/authen-api/api/v1/session-token/number' --header 'X-Session-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6ImJyZWV6eTc4NDlAZ21haWwuY29tIiwiY2xpZW50X2lkIjoiOTNhNmZiZDUtNWUxZC00YjgyLWEyYzktN2QzOTliYTMzOWJhIiwiY2xpZW50X25hbWUiOiJCcmVlenkgVGVzdCIsImlkIjoiNWJiOGMzN2QtMDZiOC00OGNkLThjZmItZDgyYjUwZDdmZTY5IiwiZXhwIjoxNzQ4NjAxMzUxLCJpYXQiOjE3NDg2MDEwNTF9.BcPwLQMi1p_CLkjqhs5qXCONy82putWBmE78m1g9XD0' --header 'X-API-Key: pjgxsalc1vi22h1t82pd'
Success Response
{ "code": "SUCCESS", "message": "Success", "data": { "secret_number": 20 } }
Error Response
{ "code": "INVALID_REQUEST", "message": "invalid session", "data": "" }
API receive verification response
The verification response will be sent to the callback_url specified in the Console, with the params request format outlined below. It is your responsibility to process this response and grant user access accordingly.
{CALLBACK_URL}?result=true&session_token={SESSION_TOKEN}
Parameters:
- result: A boolean value indicating the verification status. true means the verification was successful, while false indicates failure.
- session_token: A unique identifier for the authentication session. Your backend needs this parameter to identify the session in progress. It should compare the stored session token with the received one and proceed accordingly.
For more details: Notifying your Backend of the Verification result

Parameter	Type	Required	Description
email	string	✅ Yes	The email address of the user.
client_id	string	✅ Yes	Your application’s client ID.

Synchronizing the 2FA status

This API endpoint is responsible for synchronizing the 2FA status for a given user. Your backend must call this API whenever a user enables or disables 2FA in your application.

Request Headers

X-API-Key: API key from the Authenticator console of the application. This key is required for authentication.

Request Body Parameters

Parameter	Type	Required	Description
client_id	string	✅ Yes	Your application’s client ID.
email	string	✅ Yes	The email address of the user whose 2FA status is being updated.
action	string	✅ Yes	Must be either "ENABLE" to activate 2FA or "DISABLE" to deactivate it.
secret	string	✅ Yes*	The last known TOTP secret for the user. Required only when enabling 2FA, to verify ownership (encoded in Base32 format without padding)
type	string	✅ Yes*	The type of 2FA. Currently supports "TOTP".
algorithm	string	✅ Yes*	The hashing algorithm for TOTP generation (e.g., "SHA1").
digits	number	✅ Yes*	Number of digits in the TOTP code (typically 6).
period	number	✅ Yes*	The validity period of each TOTP code in seconds (e.g., 30).

(*) Required only when enabling 2FA

Example Request

Case ENABLE

curl --location 'https://api-authen.ekyc.com/authen-api/api/v1/mfa/toggle'   --header 'X-API-Key: ybz4gkzlgzla4u4txhn6ju'   --header 'Content-Type: application/json'   --data-raw '{
      "email": "[email protected]",
      "client_id": "CLIENT_ID",
      "secret": "SECRET_KEY",
      "action": "ENABLE",
      "type": "TOTP",
      "algorithm": "SHA1",
      "digits": 6,
      "period": 30
  }'

Case DISABLE

curl --location 'https://api-authen.ekyc.com/authen-api/api/v1/mfa/toggle' --header 'X-API-Key: ybz4gkzlgzla4u4txhn6ju' --header 'Content-Type: application/json' --data-raw '{
    "email": "[email protected]",
    "client_id": "be9da0fb-8e04-4e47-ac5f-26a3128f56b8",
    "action": "DISABLE"
}'

Success Response

{
      "code": "SUCCESS",
      "message": "Success",
      "data": ""
  }

Error Response

{
      "code": "INVALID_REQUEST",
      "message": "toggle failed",
      "data": ""
  }

QR Code Format

Option 1: Custom UI Integration (API-based)

Option 2: Redirect to WebView (Prebuilt Flow)

(*) Required only when enabling 2FA