Version 3.0C

Introduction

With MobiWeb OTP API you can provide additional security to simple username and password authentication, authenticated transactions, accurately verify users, reduce fraud and reduce two-factor authentication cost (no hardware tokens required).

The OTP API is based on REST. It uses built-in HTTP authentication and HTTP status codes. All data exchange is done in JSON format.

The OTP generation and the verification process are based on IETF RFC 6238 standard and Time-Based One-Time Password Algorithm (TOTP).

To test the OTP API, you will need a valid API account. If you don't have one yet, click here to register for a FREE account.

Authentication

https://[HOST]/apis/auth

OTP

https://[HOST]/apis/otp/v3/

[HOST]

Replace [HOST] with your API account domain name or IP.

Authentication

Each request must be accompanied by a valid access_token. access_token are generated upon successful authentication. To authenticate you must send an auth request.

https://[host]/apis/auth

This request accepts parameters type with value access_token , username and password.

access_token

If the request succeeded, an authentication object is returned, which includes an access_token and a refresh_token. Otherwise, an error is returned. access_token grants you access to make requests.

Setup the Authorization HTTP header with your access_token. Authorization: Bearer dcec4eb6-035c-41a4-9871-82c5bd3ef379

access_token is valid for 30 minutes, after which it expires. To preserve connection you must either refresh with refresh_token or reset connection and request a new access_token.

refresh_token

To refresh connection you must send an auth request.

https://[host]/apis/auth

This request accepts parameters type with value "refresh_token" , refresh_token with value the refresh token, provided by a previously successful auth request.

Authentication

POST https://[HOST]/apis/auth
 
POST https://[HOST]/apis/auth
Content-Type : application/json

{
 "type" : "access_token",
 "username" : "myusername",
 "password" : "mypassword"
}
					
{
 "status_code" : 200,
 "status_message" : "OK",
 "payload" : {
	 "access_token" : "dcec4eb6-035c-41a4-9871-82c5bd3ef379",
	 "validity_period" : 1800,
	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
}
}
Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk 
//Your account username and password
$username = "";
$password = "";

$client = new MobiWeb\Rest\Client($username, $password);

Refresh Connection

POST https://[HOST]/apis/auth
Content-Type : application/json
{
 "type" : "refresh_token",
 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
}

{
 "status_code" : 200,
 "status_message" : "OK",
 "payload" : {
  "access_token" : "0e3f6ecb-7a7e-4d03-a004-d710db8978ab",
  "validity_period" : 1800,
  "refresh_token" : "ecbb4d30-6da2-4b78-998e-d01025c648f2"
}
}

Send OTP

To send an OTP you must send a generate POST request.

https://[host]/apis/otp/v3/generate

Set parameter mobile with the recipient phone number of the OTP in E.164 format.

If the request succeeded, a response object is returned, which includes the OTP id, the recipient's mobile number, cost of the OTP and the validity period of the OTP. Otherwise, an error is returned.

Send OTP

POST https://[host]/apis/otp/v3/generate
 
POST https://[HOST]/apis/otp/v3/generate
Content-Type : application/json

{
	 "mobile" : "447546756743"
}

{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 221276323,
	 	 "mobile" : "447546756743",
	 	 "cost" : "0.0500",
	 	 "valid_until" : 1449745099
	 }
}
Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk 
//Your account username and password
$username = "";
$password = "";
	  
$client = new MobiWeb\Rest\Client($username, $password);

//Generate OTP and send it via SMS to a mobile number
$otp = $client->generate(
	"44xxxxxxxxxx", //The mobile number in international E.164 format.
	"SECUREPIN", //The sender that will be displayed in the OTP SMS. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-,.) or 14 numeric characters (0-9). Special characters are not allowed.
	"Please do not share your password pin. Your password pin is: [PIN]", //The text message of OTP SMS. Remember to put placeholder [PIN] in the message. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table, you can send up to 160 characters. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table, because of the increased memory requirement for each character, you can send up to 70 characters.
	600 //The validity period of the pin in seconds. The default value is 600 seconds (10 minutes).
);

//Print the generate OTP result. Remember to store the mobile number and the OTP id for later use.
print_r($otp);

Validate OTP

To validate an OTP you must send a validate POST request.

https://[host]/apis/otp/v3/validate/{id}

Replace {id} with the id of the otp.

Set parameter pin with the otp pin and mobile with the recipient's mobile number that received the otp in E.164 format.

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

Validate OTP

POST https://[host]/apis/otp/v3/validate/{id}
 
POST https://[HOST]/apis/otp/v3/validate/221276323
Content-Type : application/json

{
	 "pin" : 059647,
	 "mobile" : "447546756743"
}

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}
Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk 
//Your account username and password
$username = "";
$password = "";

$client = new MobiWeb\Rest\Client($username, $password);

//Validate a previously generated OTP with the OTP ID. OTP is provided by the mobile number subscriber.
$otp = $client->validate(
"564xxx", //The OTP ID returned by the generated OTP.
"44xxxxxxxxxx", //The mobile number of the subscriber in international E.164 format.
"265xxx" //The OTP provided by the mobile number subscriber.
);

//Print the OTP validation attempt result. If result is TRUE, OTP is validated.
print_r($otp);

Get Balance

To get your account's balance you must send a balance GET request.

https://[host]/apis/otp/v3/balance

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned, which includes your account balance. Otherwise, an error is returned.

Get Balance

GET https://[host]/apis/otp/v3/balance
 
GET https://[host]/apis/otp/v3/balance
Content-Type : application/json

{
 "status_code" : 200,
 "status_message" : "OK",
 "payload" : {
	 "balance" : "7845.3500"
 }
}
Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk 
//Your account username and password
$username = "";
$password = "";
  
$client = new MobiWeb\Rest\Client($username, $password);

//Get account balance and print it
echo $client->getBalance();

Get Pricing

To get your account’s pricing details and covered networks, you must make a pricing GET request.

https://[host]/apis/otp/v3/pricing

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned, which includes your account currency and an array of network objects with coverage and pricing information. Network objects have attributes operator id, operator countryname, operatorname, operator mobile country code mcc, operator mobile network code mnc and your acount price per SMS sent to this network. Otherwise, an error is returned.

Get Pricing

GET https://[host]/apis/otp/v3/pricing
 
GET https://[host]/apis/otp/v3/pricing
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "currency" : {
			 "name" : "Euro",
			 "symbol" : "EUR"
		 },
		 "pricing" : [
		 	{
			  "id" : 473,
			  "countryname" : "Afghanistan",
			  "operatorname" : "Roshan",
			  "mcc" : "412",
			  "mnc" : "020",
			  "price" : "0.0190"
		 	},
			 ..............
		 ]
	 }
}

Errors

OTP API uses 2 levels of errors. Conventional HTTP status codes and application error codes.

OTP API raises errors for many reasons (authentication, invalid parameters, network / server errors etc.). Consult the detailed HTTP status codes and application error codes tables for detailed explanation of response codes.

Application Errors

OTP API returns errors in an array of objects.

Object Attributes

  • code numeric

    Application error code identifying error.

  • message string

    A human-readable message providing more details about the error.

Errors

{
	 "status_code" : 404,
	 "status_message" : "Not found",
	 "errors" : [
		{
			 "code" : 1007,
			 "message" : "URI not found"
		}
	 ]
}

HTTP Status Codes

200 OK Everything worked as expected.
201 Created Resource created successfully.
400 Bad Request The request was unacceptable, often due to invalid JSON format.
401 Unauthorized No valid API key provided.
404 Not Found The requested resource doesn't exist.
422 Unprocessable Request The request unprocessable, often due to invalid parameters.
500 Internal Server Error The service is temporarily unavailable.

Application Error Codes

1009 Invalid access token Access token is invalid.
2100 OTP unavailable You account does not have permissions to use OTP service.
2101 Unknown destination Unknown destination.
2102 Forbidden destination Forbidden destination.
2103 Invalid mobile Invalid parameter.
2104 Invalid sender Invalid parameter. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-) or 14 numeric characters (0-9). Special characters are not allowed.
2105 Invalid message Invalid parameter.
2106 Invalid message length Invalid message length. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table, you can send up to 160 characters. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table, because of the increased memory requirement for each character, you can send up to 70 characters.
2107 Invalid pin Invalid parameter.
2108 Pin expired This pin has expired and cannot be validated.
2109 Pin already consumed This pin has been already validated.
2120 Invalid pin This pin is invalid for the combination of mobile and id provided.
2121 Service temporary unavailable Service is currently unavailable.

The AUTH Request

POST

The auth request is used to authenticate and gain access to the HLR API requests.

Parameters

  • type required predefined string "access_token" , "refresh_token"

    The type of the auth request. Can be "access_token" to reset connection or "refresh_token" to refresh connection.

  • username required for type "access_token" string

    The username of your HLR API account.

  • password required for type "access_token" string

    The password of your HLR API account.

  • refresh_token required for type "refresh_token" string

    The refresh_token. Used when refreshing the connection.

Response

If the request succeeds, an authentication object is returned. An access_token for HLR API requests and a refresh_token to refresh the connection are provided. Returns an error on failure.

Object Attributes

  • access_token string

    The access_token to use with the HLR API requests.

  • validity_period numeric

    The validity period of access_token and refresh_token.

  • refresh_token string

    The refresh_token to use when refreshing the connection.

/auth

POST https://[HOST]/apis/auth
 
POST https://[HOST]/apis/auth
Content-Type : application/json

{
	 "type" : "access_token",
	 "username" : "myusername",
	 "password" : "mypassword"
}

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "access_token" : "dcec4eb6-035c-41a4-9871-82c5bd3ef379",
	 	 "validity_period" : 1800,
	 	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
	 }
}

The GENERATE Request

POST

The generate POST request is used to generate otp pins and send them via SMS.

Body Parameters

  • mobile required numeric

    The mobile number of the pin recipient in E.164 format.

  • sender optional ( Default "SECUREPIN" ) string

    The sender that will be displayed in the OTP SMS.

  • validity optional ( Default 600 ) numeric

    The validity period of the pin in seconds.

  • message optional ( Default "Please do not share your password pin. Your password pin is: [PIN]" ) string

    The text message of OTP SMS. Remember to put placeholder [PIN] in the message. Invalid message length. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table, you can send up to 160 characters. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table, because of the increased memory requirement for each character, you can send up to 70 characters.

Response

If the request succeeds, an otp object is returned. Returns an error on failure.

Object Attributes

  • id numeric

    The id of created otp pin.

  • mobile numeric

    The otp pin recipient's mobile number in E.164 format.

  • cost numeric

    The cost of created otp pin.

  • valid_until numeric

    The validity period of created otp pin.

/generate

POST https://[HOST]/apis/otp/v3/generate
 
POST https://[HOST]/apis/otp/v3/generate
Content-Type : application/json

{
	 "mobile" : "447546756743",
     "sender" : "SecurePIN",
     "validity" : 120,
	 "message" : "Your secure pin is [PIN]"
}

{
   "status_code" : 201,
   "status_message" : "Created",
   "payload" : {
       "id" : 221276324,
       "mobile" : "447546756743",
       "cost" : "0.0500",
       "valid_until" : 1449745219
   }
}

The VALIDATE Request

POST

The validate POST request is used to validate otp pins.

URL Parameters

  • id required numeric

    The id of the otp pin, provided by a previously successful generate request.

Body Parameters

  • mobile required numeric

    The recipient's mobile number of the otp pin.

  • pin required string

    The otp pin.

Response

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

/validate

POST https://[HOST]/apis/otp/v3/validate/{id}
 
POST https://[HOST]/apis/otp/v3/validate/221276324
Content-Type : application/json

{
     "mobile" : "447546756743",
     "pin" : 725964
}

{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : ""
}

The BALANCE Request

GET

The balance GET request is used to get an account's balance.

Response

If the request succeeds, an object with the current account's balance is returned. Returns an error on failure.

Object Attributes

  • balance string

    The balance of your account.

/balance

GET https://[host]/apis/otp/v3/balance
 
GET https://[host]/apis/otp/v3/balance
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "balance" : "7845.3500"
	 }
}

The PRICING Request

GET

The pricing GET request is used to get your account’s pricing details and covered networks.

Response

If the request succeeds, an object is returned, which includes your account currency and an array of network objects with coverage and pricing information. For an operator with multiple MNCs, a separate record will be displayed for each one. Returns an error on failure.

Object Attributes

  • currency object

    currency object.

    • name string

      The name of your account's currency.

    • symbol string

      The symbol of your account's currency.

  • pricing array

    Array of pricing objects.

    • id numeric

      Mobile network operator id.

    • countryname string

      Mobile network operator country.

    • operatorname string

      Mobile network operator name.

    • mcc string

      Mobile country code of mobile operator.

    • mnc string

      Mobile network code of mobile operator.

    • price string

      Price per SMS for this mobile operator.

/pricing

GET https://[host]/apis/otp/v3/pricing
 
GET https://[host]/apis/otp/v3/pricing
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "currency" : {
			 "name" : "Euro",
			 "symbol" : "EUR"
		 },
		 "pricing" : [
          {
             "id" : 473,
             "countryname" : "Afghanistan",
             "operatorname" : "Roshan",
             "mcc" : "412",
             "mnc" : "020",
             "price" : "0.0190"
          },
          ..............
		 ]
	 }
}