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.
The integration process involves initiating the 2FA workflow, handling the authentication request, and processing the user’s verification through a webview interface.
- 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.
- 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:
- 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
, orSHA512
- Replace
- 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
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.
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.
- 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.
You can integrate the 2FA authentication step in two ways, depending on your needs:
- 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 ExampleSuccess ResponseCase of inactive client – This indicates that your application has been marked as inactive in the Domain ConsoleError Response - 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 ExampleSuccess ResponseError Response - 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.Parameters:
result
: A boolean value indicating the verification status.true
means the verification was successful, whilefalse
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 - 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 ENABLECase DISABLESuccess Response
Error Response