3. Introduction
mPass is an OATH-compliant comprehensive solution for enabling Multi-Factor authentication for enterprise applications.
mPass provides HTTP-based web services for enterprise applications to verify the mobile numbers of their users using One Time Passwords(OTP) delivered to their mobile phones.
3.1 Purpose
The purpose of this document is to provide the technical details required for Enterprise application developers to integrate their applications with mPass Authentication Server to verify mobile numbers via One Time Passwords (OTP) of their users via Mobile Number Verification (MNV) service
3.2 Pre-requisites
Before starting the integration with mPass web services, the following information should be exchanged between developers and mPass administrators.
Application server IP (mPass service Caller) - to be provided by application developers to mPass administrators.
Host Name/IP of the mPass Authentication server- to be provided by mPass administrators to application developers.
Establish HTTPS(TCP) Connection between the Application server and mPass Authentication server on port 443.
Define SMS gateway in mPass Authentication server via Administrator portal. (see administration portal)
3.3 mPass MNV Deployment
Following is the general deployment of mPass MNV service.
4. Security
4.1 Client Authentication
The enterprise application is provided with a unique Channel Key to authenticate and identify the caller.
The Channel Key can be generated from the channels screen of the mPass Administration portal. Please ask the mPass administrator to provide a Channel Key to be generated for the IP address of the application server integrating with the Mobile Number Verification services. The Web Service clients requesting services should pass this key to the mPass system.
5. Web Services Integration
The Web Services hosted by mPass Application are HTTP based web services. Software developers who want to integrate with the web services should follow the following guide.
All the response output of the services is a JSON Object.
Following is a description of the web service endpoints:
5.1 General Requests
5.1.1 Send SMS
This service is used to send OTP via SMS to the provided destination mobile number.
Operation Name | sendSMS | ||
URL | http(s)://hostname>/mpass-web/rest/mv/msg | ||
HTTP Operation Type | GET | ||
Description | To send OTP via SMS to the mobile number mentioned | ||
Request Parameters | Parameter name | Description | Requirement |
apikey | This acts as a password to uniquely identify the caller of the service. | Mandatory | |
dest | Mobile Number of the User | Mandatory | |
lang (ar_SA/en_US) | The language for the SMS. | Optional default en_US. | |
app | The Application Identifier sending the message | Optional If sent, the validation message should include it. | |
Response | The Web Service operation returns the following values for the cases mentioned: Response Codes are sent in JSON Format: Eg:- {"description":"Accept","status":"0"}
Status Codes: ACCEPT(0,"Accept"), INVALID_INPUT(1,"Invalid Data"), INVALID_CLIENT(2,"Access Denied"), INTERNAL_ERROR(100,"Internal Error Occurred") | ||
5.1.2 Verify OTP
This service is used to validate OTP sent via SMS to the mobile number
Operation Name | Verify OTP | ||
URL | http(s)://hostname>/mpass-web/rest/mv/verify | ||
HTTP Operation Type | GET | ||
Description | To verify the OTP sent via SMS for the mobile number | ||
Request Parameters | Parameter name | Description | Requirement |
apikey | This acts as a password to uniquely identify the caller of the service. | Mandatory | |
dest | Mobile Number of the User | Mandatory | |
otp | The One Time Password to verify received earlier via SMS) | Mandatory | |
app | The Application Identifier sending the message | Optional Should be set if set earlier in the Send SMS request. | |
Response | The Web Service operation returns the following values for the cases mentioned: Response Codes are sent in JSON Format: Eg:- {"description":"Accept","status":"0"}
Status Codes: ACCEPT(0,"Accept"), INVALID_INPUT(1,"Invalid Data"), INVALID_CLIENT(2,"Access Denied"), REJECT(3,"Reject"), EXPIRED(4,"Expired"), INTERNAL_ERROR(100,"Internal Error Occurred")
| ||
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article