Welcome
With MessageHub 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 MessageHub OTP API, you will need a valid API account. If you don't have one yet please register your account.
Examples
Authentication Endpoint
https://app.messagehub.nl/apis/auth/OTP API Endpoint
https://app.messagehub.nl/apis/otp/v3/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://app.messagehub.nl/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. AuthorizationBearer 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://app.messagehub.nl/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.
Examples
Authentication
POST https://app.messagehub.nl/apis/auth/
POST https://app.messagehub.nl/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"
}
}Refresh Connection
POST https://app.messagehub.nl/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://app.messagehub.nl/apis/otp/v3/generate/
Set parameters 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.
Examples
Send OTP
POST https://app.messagehub.nl/apis/otp/v3/generate/
POST https://app.messagehub.nl/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
}
}Validate OTP
To validate an OTP you must send a validate POST request.
https://app.messagehub.nl/apis/otp/v3/validate/{id}
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.
Examples
Validate OTP
POST https://app.messagehub.nl/apis/otp/v3/validate/{id}
POST https://app.messagehub.nl/apis/otp/v3/validate/221276323
Content-Type : application/json
{
"pin" : 059647,
"mobile" : "447546756743"
}
{
"status_code" : 200,
"status_message" : "OK",
"payload" : ""
}Get Balance
To get your account's balance you must send a balance GET request.
https://app.messagehub.nl/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.
Examples
Get Balance
GET https://app.messagehub.nl/apis/otp/v3/balance/
GET https://app.messagehub.nl/apis/otp/v3/balance/
Content-Type : application/json
{
"status_code" : 200,
"status_message" : "OK",
"payload" : {
"balance" : "7845.3500"
}
}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.
| CODE numeric | MESSAGE string |
|---|---|
| Application error code identifying error. | A human-readable message providing more details about the error. |
Examples
Errors
{
"status_code" : 404,
"status_message" : "Not found",
"errors" : [
{
"code" : 1007,
"message" : "URI not found"
}
]
}HTTP Status Codes
| code# | STATUS | MESSAGE |
|---|---|---|
| 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
| code# | STATUS | MESSAGE |
|---|---|---|
| 1009 | Invalid access token | Access token is invalid. |
| 2100 | OTP unavailable | Your 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. |