To generate OTP using Karix Authenticator API service, you should:
Have an account with Karix with privileges to use Karix Authenticator service.
Have a system that has public internet connectivity and should have access to IP provided by Karix.
Have a user’s mobile number registered at your end.
Have a user’s email id registered at your end.
AUTHENTICATOR MECHANISM
This section details the steps involved in the mechanism of the authenticator:
1. OTP Generation Process
2. OTP Validation Process
3. OTP Regeneration Process
OTP Generation Process
Karix OTP authenticator API will receive the request to generate OTP with the below parameters
Header Values:
access_key
Query String prams:
ipaddress, mobile, email
Karix OTP authenticator API will read the header values and authenticate with the access_key. If it’s valid user it will process the request for further, otherwise it will send the unauthorised user error response (UNAUTHERISED USER) to the client.
On successful authentication Karix OTP authenticator API will check whether the account is enabled with OTP authentication feature. If the feature is enabled application will generate the OTP as below.
a. If there is no opt for the received mobile and ip address, it will generate numeric new OTP based on the configured length at Karix system.
b. If any of the OTP generated with the received mobile and ip address, it will mark as expire and generate numeric new OTP based on the configured length at Karix system.
On successful generation of OTP, it will send the OTP as SMS/Email to end user based on the configuration for the configured accounts and send the response as "OTP Generated Successfully" to client as part of request.
End Point URL
Example:
https://auth.instaalerts.zone/otpauthapi/otpgenservlet? ipaddress=10.20.51.122&mobile=919551492394&email=selangovan@karix.com
NOTE: email is optional parameter, if the service enabled with Email option, OTP will be sent as email.
OTP Validation Process
Karix OTP authenticator API will receive the request to generate OTP with the below parameters
Header Values:
access_key
Query String prams:
mobile, ipaddress, otp
If the received OTP is valid, the authenticator will check for the expiry of the OTP. If the OTP is expired, the authenticator API will send the response as "OTPEXPIRED" to client.
If the OTP is active, the Karix Authenticator API will send the response to client as "Verified successfully".
If the received OTP is not matching with OTP values with Karix system, Authenticator API will treat as invalid OTP and it will check for the max OTP validate attempts. If the max OTP validate attempts reached, it will send the response to client as "Max no of tries for this pin been reached. Please generate other".
If the max OTP validate attempts is less than the configured threshold value, it will send the response to client as "Wrong PIN. No of Retries remaining #no.of attempt value".
End Point URL
Example:
https://auth.instaalerts.zone/otpauthapi/otpvalidationservlet? ipaddress=10.20.51.122&otp=ca7dc0a35226c1c6ca19fd9c673f442f&mobile=919500070292
NOTE: the OTP parameter values should be encrypted with AES 256 Algorithm and should be encoded.
OTP Regeneration Process
Karix OTP authenticator API will receive the request to re generate OTP with the below parameters
Header Values:
access_key
Query String prams:
ipaddress, mobile, email
Karix OTP authenticator API will read the header values and authenticate with the access_key. If it’s valid user it will process the request for further, otherwise it will send the (UNAUTHERISED USER) error response to client.
If the OTP is valid, authenticator checks for the max attempt of regeneration. If the max regen attempts more than the configured threshold at Karix end, it will send the response to client as "Max no of tries to regeneration of pin has been reached. Please generate other".
If the max attempts less than the configured threshold at Karix level, it will get the available latest OTP from Karix system for the received mobile and ip address. Authenticator API will send the OTP as SMS/Email using the configured accounts and Karix authenticator will send response to client as "OTP Generated Successfully".
While sending the SMS/Email, the authenticator will check which channel is enabled for the account. If the SMS channel enabled, it will send only SMS. If both SMS/Email enabled, it will send both SMS/Email.
End Point URL
Example:
https://auth.instaalerts.zone/otpauthapi/otpregenservlet? ipaddress=10.20.51.122&mobile=919551492394&email=selangovan@karix.com
Encryption/Decrypt Logic in Java:
To Encrypt:
To Decrypt:
NOTE: key, ivParam will be shared by Karix team.
Query - SELECT * FROM otpauthapi.otp_auth_config WHERE esme_address IN (xxxxxxxx)