One Time Passwords (OTP)
PHP

Introduction

With the OTP API you can generate one time passwords and verify the response.

Protect your organisation and users against fraudulent login attempts and potential catastrophic effects on your business. CM.com offers a unique Hybrid Two-factor, One Time Password solution that can be delivered via our high quality SMS routes or to your app via Push.

How to start:

  1. Register for an account at https://www.cm.com/register/
  2. Retrieve your API product token via the 'Messaging Gateway' app at https://www.cm.com/app/gateway/

Version 1.0

The Base URL is https://api.cmtelecom.com

HTTP Headers:

X-CM-ProductToken - your product token (string)

OTP API end points

Generate code

POST /v1.0/otp/generate
Content-Type: application/json

Parameters:

required

  • recipient (string) - phone number in international format. e.g. 0031601234567
  • sender (string) - name of the sender (min 3, max 11)

Please note that alphanumeric sender is not supported in all countries.

optional

  • length - length of the code (min 4, max 10, integer) (default = 5)
  • expiry - expiry in seconds (min 10, max 3600, integer) (default = 60 seconds)
  • allowPush (boolean) - Allow code to be send via push notification (default = false)
  • appKey - The app key GUID
  • message - Set a custom message. You can use the placeholder {code} which will be replaced by the actual code. e.g. Your code is: {code}

When allowPush is set to true, a valid app key is required

Example:

{
    "recipient": "0031601234567",
    "sender": "My company"
}

Response:

  "id": "1e12cb10-d14a-4cd6-8d86-e5263cf122ee",
  "createdAt": "2015-01-01T13:00:00+0000",
  "expireAt": "2015-01-01T13:01:00+0000"
}

Verify code

POST /v1.0/otp/verify
Content-Type: application/json

Parameters:

required

  • id - code identifier (string)
  • code - the code (string)

Example:

{
    "id": "1e12cb10-d14a-4cd6-8d86-e5263cf122ee",
    "code": "12345"
}

Response:

{
  "valid": true
}

Please note: once a code has been successfully validated, it cannot be validated again.

HTTP status codes

200 = OK
400 = Validation Error (Invalid request, see message in the response)
422 = Unprocessable Entity (Could not send OTP, see message in the response)
500 = Internal Server Error (Unknown error occurred)

Sample codes

Generate code

In this way you can generate a code.

Code Examples:

PHP
$ch = curl_init();

$options = array(
    CURLOPT_URL            => 'https://api.cmtelecom.com/v1.0/otp/generate',
    CURLOPT_HTTPHEADER     => array(
        'Content-Type: application/json',
        'X-CM-ProductToken: 00000000-0000-0000-0000-000000000000',
    ),
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(array(
        'recipient' => '0031600000000',
        'sender' => 'CM Telecom',
    )),
    CURLOPT_RETURNTRANSFER => true
);

curl_setopt_array($ch, $options);
$response = curl_exec($ch);
curl_close($ch);

$generateResponse = json_decode($response);
CURL
curl -X POST
-H "Content-Type: application/json"
-H "X-CM-ProductToken: 00000000-0000-0000-0000-000000000000"
-d '{
"recipient": "0031600000000",
"sender":"CM Telecom"}' 
'https://api.cmtelecom.com/v1.0/otp/generate'
SWIFT 2.0
let data: [String : AnyObject] = [
    "recipient" : "0031600000000",
    "sender" : "CM Telecom"
]

let request = NSMutableURLRequest(URL: NSURL(string: "https://api.cmtelecom.com/v1.0/otp/generate")!)
request.HTTPMethod = "POST"
request.HTTPBody = try! NSJSONSerialization.dataWithJSONObject(data, options: [])

request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("00000000-0000-0000-0000-000000000000", forHTTPHeaderField: "X-CM-ProductToken")

let task = NSURLSession.sharedSession().dataTaskWithRequest(request) { data, response, error in
    guard error == nil else {
        print("request error: \(error)")
        return
    }
    
    if let responseData = data {
        let responseStr = NSString(data:responseData, encoding: NSUTF8StringEncoding)
        print("response: \(responseStr)")
    } else {
        print("empty response")
    }
}

task.resume()
GO
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
)

type Message struct {
	Recipient string `json:"recipient"`
	Sender    string `json:"sender"`
}

func main() {
	url := "https://api.cmtelecom.com/v1.0/otp/generate"

	msg := Message{
		Recipient: "0031600000000",
		Sender:    "CM Telecom",
	}

	postData, err := json.Marshal(msg)
	if err != nil {
		panic(err)
	}

	req, _ := http.NewRequest("POST", url, bytes.NewReader(postData))
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("X-CM-ProductToken", "00000000-0000-0000-0000-000000000000")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(string(body))
}

Verify code

In this way you can verify a code.

Code Examples:

PHP
$ch = curl_init();

$options = array(
    CURLOPT_URL            => 'https://api.cmtelecom.com/v1.0/otp/verify',
    CURLOPT_HTTPHEADER     => array(
        'Content-Type: application/json',
        'X-CM-ProductToken: 00000000-0000-0000-0000-000000000000',
    ),
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode(array(
        'id' => '1e12cb10-d14a-4cd6-8d86-e5263cf122ee',
        'code' => '12345',
    )),
    CURLOPT_RETURNTRANSFER => true
);

curl_setopt_array($ch, $options);
$response = curl_exec($ch);
curl_close($ch);

$verifyResponse = json_decode($response);
CURL
curl -X POST \
  https://api.cmtelecom.com/v1.0/otp/verify \
  -H 'Content-Type: application/json' \
  -H 'X-CM-ProductToken: 00000000-0000-0000-0000-000000000000' \
  -d '{
    "id": "1e12cb10-d14a-4cd6-8d86-e5263cf122ee",
    "code": "12345"
}'