API Guide to set up OTP verification

OVERVIEW

The security breaches that are caused due to spammers and scammers have led to the loss of reliability and eventually loss of business. Need for instant secure connection has thus become a priority. OTP verification is the most secure way to log in to the platform which users use frequently. This can be done by configuring bulk SMS API. Setting up OTP verification can give users more promising and safe environment to use mobile phones for business, banking, shopping and many other important transactions. Authenticating the users, password resetting, upgrading the authorization and so on are the instances where enterprise users demand OTP verification. OTP verification not only sets up security on phone but also for personal computers.

This Step by Step guide gives instructions on how you can integrate miniOrange OTP Verification service with your phone as well as PC.

STEP 1: CREATE AUTHENTICATION HEADER

To call our challenge and validate Rest APIs, you will need to set the authorization headers required to make sure that the request being made is by a valid user. You can check the sample JAVA and PHP code below to get an idea of how you can create the authorization headers.

The following values need to be set in the Header of the HTTP Request being made. This will be common for both, OTP request and OTP validation calls.

Attribute	Description
Customer-Key	Your customer key.
Timestamp	The time in milliseconds when the request is being made.
Authorization	Sha 512 Hash Value consisting of the customer key ,current timestamp and api key.

You can get these values by following these steps:

Go to https://login.xecurify.com/moas/login
Log in using your miniOrange credentials.
Click on the Settings from the right hand upper side.
You will find all the necessary information from the table under General Settings section.

SAMPLE CODE:

JAVA

/* JSON Object format for challenge API request */
{
  /* You can get customer Key and customer Api Key from
	https://login.xecurify.com/moas/customerconfigurations*/
	String customerKey = "<YOUR_CUSTOMER_KEY>";
	String apiKey = "<YOUR_API_KEY>";
	/* Current time in milliseconds since midnight, January 1, 1970 UTC. */
	String currentTimeInMillis = String.valueOf(System.currentTimeMillis());
	/* Creating the Hash using SHA-512 algorithm (Apache Shiro library) */
	String stringToHash = customerKey + currentTimeInMillis + apiKey;
	String hashValue = new Sha512Hash(stringToHash).toHex().toLowerCase();
	HttpPost postRequest = new HttpPost("");
	/* Setting the Authorization Header values */
	postRequest.setHeader("Customer-Key", customerKey);
	postRequest.setHeader("Timestamp", currentTimeInMillis);
	postRequest.setHeader("Authorization", hashValue)
}

PHP

/* JSON Object format for challenge API request */
{
  /* You can get customer Key and customer Api Key from
	https://login.xecurify.com/moas/customerconfigurations*/
	$customerKey = "<YOUR_CUSTOMER_KEY>";
	$apiKey = "<YOUR_API_KEY>";
	/* Current time in milliseconds since midnight, January 1, 1970 UTC. */
	$currentTimeInMillis = round(microtime(true) * 1000);
	/* Creating the Hash using SHA-512 algorithm */
	$stringToHash = $customerKey . number_format ( $currentTimeInMillis, 0, '', '' ) .
	$apiKey;
	$hashValue = hash("sha512", $stringToHash);
	/* Add $customerKeyHeader,$timestampHeader and $authorizationHeader in the
   httpheader */
	$customerKeyHeader = "Customer-Key: " . $customerKey;
	$timestampHeader = "Timestamp: " . number_format ( $currentTimeInMillis, 0, '', ''
	);
	$authorizationHeader = "Authorization: " . $hashValue;
}

STEP 2: OTP GENERATION / CHALLENGE REST API

You need to make a HTTP POST request to our OTP generation / Challenge Rest API in order to be able to generate OTP for the phone number. Our Challenge Rest API accepts the JSON input in the following format:

/* JSON Object format for generation request */

{ "customerKey":"<OUR_CUSTOMER_KEY>", /* Your customer key */*/ "phone":"<PHONE_NUMBER_TO_SEND_OTP_TO>" /* phone number to send OTP to */ "email":"<EMAIL_TO_SEND_OTP_TO>" /* email address to send OTP to */ "authType":"SMS or EMAIL" /* Denotes that you need to */ "transactionName":"CUSTOM-OTP-VERIFICATION", }

OTP Generation Endpoint : https://login.xecurify.com/moas/api/auth/challenge

Attribute	Description
Customer-Key*	Your customer key.
phone	The phone number where you would like us to send OTP to.
email	The Email Address where you would like us to send OTP to.
authType *	The authentication method. In this case: SMS or Email
transactionName	Any transaction details that you would like to send to user to give information about the transaction. (Max limit 30 characters) Keep this as CUSTOM-OTP-VERIFICATION

The following is the JSON Response generated by the Generate Rest API.

/* JSON Response Object for Generation Request */
{
	"txId: "<UNIQUE_TRANSACTION_ID>",
	"authType: "SMS or Email",
	"responseType: "CHALLENGE",
	"phoneDelivery": {
  	"contact": "<PHONE_NUMBER_OTP_WAS_SENT_TO>,
  	"sendStatus": "SUCCESS",
  	"sendTime": "<TIMESTAMP>"
	},
	"emailDelivery": {
  	"contact": "<EMAIL_ADDRESS_OTP_WAS_SENT_TO>,
  	"sendStatus": "SUCCESS",
  	"sendTime": "<TIMESTAMP>"
	}
	"status": "SUCCESS",
	"message": "Successfully generated."
}

Attribute	Description
txId	This is the transaction ID for your generation request. You will need to save this value in session. This will need to be sent in the validation API.
authType	The authentication method . In this case it’s SMS
responseType	This shows the type of response i.e. Response for Challenge request or Validate request. Valid values: CHALLENGE
phoneDelivery	The phone delivery status. It is provided in case authentication is done through to mobile.
contact	The phone number OTP was sent to i.e. mobile.
sendStatus	The status of sending the above contact. Valid values: SUCCESS, FAILED, ERROR
sendTime	Timestamp showing time of sending.
message	An additional message showing overall status of the request.
status	Overall status of the challenge/validation request. Valid values: SUCCESS, FAILED, ERROR

SAMPLE CODE:
JAVA

/* JSON Object format for challenge API request */
{
  /* The challenge rest api url which needs to be called to challenge the user. */
	String generateUrl = "https://login.xecurify.com/moas/api/auth/challenge";
	 /* The customer Key provided to you */
	String customerKey = "<YOUR_CUSTOMER_KEY>";
	 /* The customer API Key provided to you */
	String apiKey = "<YOUR_API_KEY>";
	 /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
	String currentTimeInMillis = String.valueOf(System.currentTimeMillis());
	 /* Creating the Hash using SHA-512 algorithm (Apache Shiro library) */
	String stringToHash = customerKey + currentTimeInMillis + apiKey;
	String hashValue = new Sha512Hash(stringToHash).toHex().toLowerCase();
	/* The JSON string containing the request information */
	String jsonRequestString = "{\"customerKey\":\"" + customerKey +
  	",\"email\" : \"<email>\" "+
  	",\"phone\":\"<phone number>\" "+
  	",\"authType\" : \"<SMS or EMAIL>\" "+
  	",\"transactionName\" : \"CUSTOM-OTP-VERIFICATION\"}";
	/* Initializing default Http Client */
	HttpClient httpClient = new DefaultHttpClient();
	HttpPost postRequest = new HttpPost(generateUrl);
	 /* Setting jsonRequestString as StringEntity */
	StringEntity input = new StringEntity(jsonRequestString);
	input.setContentType("application/json");
	postRequest.setEntity(input);
	 /* Setting the Authorization Header values */
	postRequest.setHeader("Customer-Key", customerKey);
	postRequest.setHeader("Timestamp", currentTimeInMillis);
	postRequest.setHeader("Authorization", hashValue);
	 /* Calling the rest API */
	HttpResponse httpResponse = httpClient.execute(postRequest);
	 /* If invalid response is received, throwing a Runtime Exception */
	if (httpResponse.getStatusLine().getStatusCode() != 200) {
  	throw new RuntimeException("Invalid response received from authentication");
  }
  /* If a valid response is received, get the JSON response string */
	BufferedReader br = new BufferedReader(new
	InputStreamReader((httpResponse.getEntity().getContent())));
	String output, jsonResponseString = "";
	while ((output = br.readLine()) != null) {
  	jsonResponseString += output;
	}
	httpClient.getConnectionManager().shutdown();
	return jsonResponseString;
}

PHP

{
  /* The challenge rest api url which needs to be called to challenge the user. */
	$generateUrl = "https://login.xecurify.com/moas/api/auth/challenge";
	 /* The customer Key provided to you */
	$customerKey = "<YOUR_CUSTOMER_KEY>";
	 /* The customer API Key provided to you */
	$apiKey = "<YOUR_API_KEY>";
	 /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
	$currentTimeInMillis = round(microtime(true) * 1000);
	 /* Creating the Hash using SHA-512 algorithm */
	$stringToHash = $customerKey . number_format ( $currentTimeInMillis, 0, '', '' ) .
	$apiKey;
	$hashValue = hash("sha512", $stringToHash);
	 /* The Array containing the request information */
	$jsonRequest = array(
    	"customerKey" => $customerKey,
    	"phone" => "<phone number>",
    	"email" => "<email>",
    	"authType" => "<SMS or EMAIL>",
    	"transactionName" => "CUSTOM-OTP-VERIFICATION"
  );
	 /* JSON encode the request array to get JSON String */
	$jsonRequestString = json_encode($jsonRequest);
	$customerKeyHeader = "Customer-Key: " . $customerKey;
	$timestampHeader = "Timestamp: " . number_format ( $currentTimeInMillis, 0, '', ''
	);
	$authorizationHeader = "Authorization: " . $hashValue;
	 /* Initialize curl */
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: application/json",
	$customerKeyHeader,$timestampHeader, $authorizationHeader));
	curl_setopt($ch, CURLOPT_URL, $generateUrl);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
	curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
	curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
	curl_setopt($ch, CURLOPT_VERBOSE, TRUE);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequestString);
	curl_setopt($ch, CURLOPT_POST, 1);
	 /* Calling the rest API */
	$result = curl_exec($ch);
	if (curl_errno($ch)) {
  	print curl_error($ch);
	} else {
  	curl_close($ch);
	}
	 /* If a valid response is received, get the JSON response */
	$response = (array)json_decode($result);
	$status = $response['status'];
	if($status == 'SUCCESS') {
  	return "SUCCESS";
	} else {
  	return "FAILED: " . $response['message'];
  }
}

cURL


	curl --insecure --location --verbose \
	-H "Content-Type: application/json" \
	-H "Customer-Key: <customer-key>" \
	-H "Timestamp: <current-timestamp>" \
	-H "Authorization: <Hash-Value>" \
	-d '{"customerKey" : "<customerKey>","phone": "<phone number>","email":"<email>" \
	,"authType":"<SMS or EMAIL>","transactionName":"CUSTOM-OTP-VERIFICATION"}' \
	"https://login.xecurify.com/moas/api/auth/challenge"

STEP 3: OTP VALIDATION / VERIFY CHALLENGE REST API

To validate an OTP, in case authentication method is SMS, EMAIL or PHONE VERIFICATION, you need to make an HTTP POST request to our Validate Rest API. Our Validate Rest API accepts the JSON input in the following format:

/* JSON Object for Validation Request */

{ "txId": "fc727646-7c91-11e5-883e-0e2fb063e0f9", "token": "123456" }

Our validate API is: https://login.xecurify.com/moas/api/auth/validate

Attribute	Description
txId	The transaction ID for which request was generated. This is sent as a response parameter in the Generate API.
token	The OTP token user entered to verify.

The following is the JSON Response generated by the Validate Rest API.

/* JSON Response Object for Validation Request */
{
	txId: "<UNIQUE_TRANSACTION_ID>"
	responseType: "VALIDATE"
	status: "SUCCESS"
	message: "Successfully Validated"
}

Attribute	Description
txId	This is the transaction ID for your generation request..
responseType	This shows the type of response i.e. Response for Generate request or Validate request. Valid values: VALIDATE
status	Overall status of the generation/validation request. Valid values: SUCCESS, ERROR, FAILED.
message	An additional message showing overall status of the request.

SAMPLE CODE:
JAVA

{
  /* The challenge rest api url which needs to be called to challenge the user. */
	String validateUrl = "https://login.xecurify.com/moas/api/auth/validate";
	 /* The customer Key provided to you */
	String customerKey = "<YOUR_CUSTOMER_KEY>";
	 /* The customer API Key provided to you */
	String apiKey = "<YOUR_API_KEY>";
	 /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
	String currentTimeInMillis = String.valueOf(System.currentTimeMillis());
	 /* Creating the Hash using SHA-512 algorithm (Apache Shiro library) */
	String stringToHash = customerKey + currentTimeInMillis + apiKey;
	String hashValue = new Sha512Hash(stringToHash).toHex().toLowerCase();
	 /* The JSON string containing the request information */
	String jsonRequestString = "{\"txId\":\"" + <txId value for corresponding OTP> + 
        	",\"token\":\"<OTP received>\"}";
	 /* Initializing default Http Client */
	HttpClient httpClient = new DefaultHttpClient();
	HttpPost postRequest = new HttpPost(validateUrl);
	 /* Setting jsonRequestString as StringEntity */
	StringEntity input = new StringEntity(jsonRequestString);
	input.setContentType("application/json");
	postRequest.setEntity(input);
	 /* Setting the Authorization Header values */
	postRequest.setHeader("Customer-Key", customerKey);
	postRequest.setHeader("Timestamp", currentTimeInMillis);
	postRequest.setHeader("Authorization", hashValue);
	 /* Calling the rest API */
	HttpResponse httpResponse =
	httpClient.execute(postRequest);
	 /* If invalid response is received, throwing a Runtime
  	Exception */
	if (httpResponse.getStatusLine().getStatusCode() != 200) {
  	 throw new RuntimeException("Invalid response
  	received from authentication server. HTTP error code: "
  	+ response.getStatusLine().getStatusCode());
	}
	 /* If a valid response is received, get the JSON response
  	string */
	BufferedReader br = new BufferedReader(new
	InputStreamReader((httpResponse.getEntity().getContent())));
	String output, jsonResponseString = "";
	while ((output = br.readLine()) != null) {
  	jsonResponseString += output;
	}
	httpClient.getConnectionManager().shutdown();
	return jsonResponseString;
}

PHP

{
  /* The challenge rest api url which needs to be called to validate the user. */
	$validateUrl = "https://login.xecurify.com/moas/api/auth/validate";
	 /* The customer Key provided to you */
	$customerKey = "<YOUR_CUSTOMER_KEY>";
	 /* The customer API Key provided to you */
	$apiKey = "<YOUR_API_KEY>";
	 /* Current time in milliseconds since midnight, January 1, 1970 UTC. */
	$currentTimeInMillis = round(microtime(true) * 1000);
	 /* Creating the Hash using SHA-512 algorithm */
	$stringToHash = $customerKey . number_format ( $currentTimeInMillis, 0, '', '' ) .
	$apiKey;
	$hashValue = hash("sha512", $stringToHash);
	 /* The Array containing the validate information */
	$jsonRequest = array('txId' => <txId value for corresponding OTP>,
    	'token' => <OTP received>);
	 /* JSON encode the request array to get JSON String */
	$jsonRequestString = json_encode($jsonRequest);
	$customerKeyHeader = "Customer-Key: " . $customerKey;
	$timestampHeader = "Timestamp: " . number_format ( $currentTimeInMillis, 0, '', ''
	);
	$authorizationHeader = "Authorization: " . $hashValue;
	 /* Initialize curl */
	$ch = curl_init();
	curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: application/json",
	$customerKeyHeader,$timestampHeader, $authorizationHeader));
	curl_setopt($ch, CURLOPT_URL, $validateUrl);
	curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
	curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
	curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
	curl_setopt($ch, CURLOPT_VERBOSE, TRUE);
	curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonRequestString);
	curl_setopt($ch, CURLOPT_POST, 1);
	 /* Calling the rest API */
	$result = curl_exec($ch);
	if (curl_errno($ch)) {
  	print curl_error($ch);
	} else {
  	curl_close($ch);
	}
	/* If a valid response is received, get the JSON response */
	$response = (array)json_decode($result);
	$status = $response['status'];
	if($status == 'SUCCESS') {
  	return "SUCCESS";
	} else {
  	 return "FAILED: " . $response['message'];
	}

cURL


	curl --insecure --location --verbose \
	-H "Content-Type: application/json" \
	-H "Customer-Key: <customer-key>" \
	-H "Timestamp: <current-timestamp>" \
	-H "Authorization: <Hash-Value>" \
	-d '{"txId" : "<transaction-id>","token": "<otp>"}' \
	"https://login.xecurify.com/moas/api/auth/validate"

STEP 4: CUSTOM SMS GATEWAY CONFIGURATION

Login to miniOrange Admin Console.
Go to Customization Tab from the menu and select SMS Gateway Configuration.
Select option Set organization SMS Gateway .
Enter you SMS Gateway url in Gateway URL field.
To Test SMS Gateway Configuration
a. Enter your phone number in Step-1 and click Test Configuration. You will get OTP if SMS Gateway url is correct.
b. If you got OTP, Enter in Step-2, and click the Validate button.
Save the configuration.

STEPS:

Create Authentication Header
OTP Generation/ Challenge REST API
OTP Validation/ Verify Challenge Rest API
Custom SMS Gateway Configuration

OVERVIEW

STEP 1: CREATE AUTHENTICATION HEADER

STEP 2: OTP GENERATION / CHALLENGE REST API

STEP 3: OTP VALIDATION / VERIFY CHALLENGE REST API

STEP 4: CUSTOM SMS GATEWAY CONFIGURATION

STEPS:

Why Our Customers choose miniOrange Secure Identity Solutions ?

24/7 Support

Affordable Pricing

STAY CONNECTED