ECS AUTHENTICATOR API DOCUMENTATION

Developer integration guide

Use the configuration API to obtain today’s receiving details, then accept customer OTP messages at your HTTPS callback.

Quick start

  1. Create an account and copy the API key from the Dashboard.
  2. Add a public HTTPS callback URL and select its HTTP method. POST is recommended.
  3. Call the configuration API once a day and securely store the returned linked number and secure code for further processing. Unnecessary API calls are not allowed.
  4. Create an OTP in your application and ask the customer to send SECURE_CODE-OTP to the linked number. Example in HTML
    <a href="sms:LINKED_PHONE_NUMBER?body=SECURE_CODE-OTP">Send OTP via SMS to LINKED_PHONE_NUMBER</a>
  5. At your callback, validate phone and message against the pending OTP in your database.
Important: ECS delivers the SMS data. Your backend (HTTPS callback URL) performs the final OTP match, expiry check, one-time-use check and customer action.

1. Configuration API

This endpoint returns the current receiving number and secure code assigned to the authenticated account. It does not search for an SMS and requires no JSON request body.

Endpoint
https://auth.electrocompsystem.com/api/v1/verifications
Method
POST
Authorization
Bearer YOUR_API_KEY
Request body
None
Successful limit
1 call every 5 minutes
Recommended time
Once daily, at a time convenient for your application
cURL
curl --request POST 'https://auth.electrocompsystem.com/api/v1/verifications' \
+  --header 'Authorization: Bearer YOUR_API_KEY' \
+  --header 'Accept: application/json'

HTTP 200 response

{
  "status": "success",
  "result": "success",
  "limit": {
    "count": 1,
    "minute": 5,
    "last_call": "2026-09-23 14:20:00"
  },
  "linked_phone_number": "9432310298",
  "secure_code": "A7K2Q9"
}

HTTP 429 response

{
  "status": "error",
  "result": "limit reached",
  "limit": {
    "count": 1,
    "minute": 5,
    "last_call": "2026-09-23 14:20:00"
  }
}

last_call is returned in Indian Standard Time. Store the API response securely for further processing using the linked number and secure code. Unnecessary API calls are not allowed.

2. Build the customer’s SMS

Create the OTP in your own backend. Join the current secure code, one hyphen and the OTP:

A7K2Q9-T855PR
A7K2Q9=secure code
- = first separator
T855PR=your OTP/message

Display both the exact SMS text and the returned linked phone number to the customer. Everything after the first hyphen is forwarded as message or OTP.

3. Receive the callback

When ECS Authenticator receives a valid SMS for your secure code, it call back the HTTPS URL saved in your Dashboard. The request uses application/x-www-form-urlencoded.

FieldTypeDescription
phoneStringSender phone number received from the system
messageStringEverything after the first hyphen; normally your OTP

Example POST body

phone=9876543210&message=T855PR

Return any HTTP status from 200 to 299 after accepting the request. Other statuses, connection errors or timeouts are logged as failed. ECS Authenticator does not follow redirects.

PHP callback receiver
<?php
declare(strict_types=1);

date_default_timezone_set('Asia/Kolkata');
header('Content-Type: application/json; charset=utf-8');

$phone = preg_replace('/\D+/', '', (string) ($_POST['phone'] ?? ''));
$message = trim((string) ($_POST['message'] ?? ''));

if (strlen($phone) === 12 && str_starts_with($phone, '91')) {
    $phone = substr($phone, 2);
}

if (
    !preg_match('/^[6-9][0-9]{9}$/', $phone) ||
    !preg_match('/^([A-Za-z0-9]{6})/', $message, $match)
) {
    http_response_code(400);
    echo json_encode([
        'status' => 'error',
        'message' => 'Invalid phone number or OTP.'
    ]);
    exit;
}

$data = [
    'status' => 'success',
    'message' => 'Callback received and logged.',
    'received_at' => date('Y-m-d H:i:s'),
    'phone' => '+91' . $phone,
    'otp' => $match[1]
];

$logged = file_put_contents(
    __DIR__ . '/callback.log',
    json_encode($data, JSON_UNESCAPED_SLASHES) . PHP_EOL,
    FILE_APPEND | LOCK_EX
);

if ($logged === false) {
    http_response_code(500);
    $data['status'] = 'error';
    $data['message'] = 'Could not write callback log.';
}

echo json_encode(
    $data,
    JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES
);

Configuration API examples

PHP 8.2+
<?php
declare(strict_types=1);

header('Content-Type: application/json; charset=utf-8');
header('Cache-Control: no-store');

$apiUrl = 'https://auth.electrocompsystem.com/api/v1/verifications';
$apiKey = 'YOUR_API_KEY';

try {
    if ($apiKey === '' || $apiKey === 'YOUR_API_KEY') {
        throw new RuntimeException('API key is not configured.');
    }

    $ch = curl_init($apiUrl);

    if ($ch === false) {
        throw new RuntimeException('Could not initialize cURL.');
    }

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Accept: application/json',
        ],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT => 15,
    ]);

    $body = curl_exec($ch);
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $curlError = curl_error($ch);

    curl_close($ch);

    if ($body === false) {
        throw new RuntimeException('API connection failed: ' . $curlError);
    }

    $data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

    if ($statusCode === 200 && ($data['status'] ?? '') === 'success') {
        $linkedNumber = (string) ($data['linked_phone_number'] ?? '');
        $secureCode = (string) ($data['secure_code'] ?? '');

        // Store $linkedNumber and $secureCode securely if required.
    }

    http_response_code($statusCode >= 100 ? $statusCode : 200);

    echo json_encode(
        $data,
        JSON_PRETTY_PRINT |
        JSON_UNESCAPED_SLASHES |
        JSON_UNESCAPED_UNICODE
    );
} catch (Throwable $error) {
    http_response_code(500);

    echo json_encode([
        'status' => 'error',
        'message' => $error->getMessage(),
    ], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
}
Python
import json
import requests

API_URL = "https://auth.electrocompsystem.com/api/v1/verifications"
API_KEY = "YOUR_API_KEY"

try:
    if not API_KEY or API_KEY == "YOUR_API_KEY":
        raise ValueError("API key is not configured.")

    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Accept": "application/json",
        },
        timeout=15,
    )

    response.raise_for_status()
    data = response.json()

    if data.get("status") == "success":
        linked_number = data.get("linked_phone_number", "")
        secure_code = data.get("secure_code", "")

        # Store linked_number and secure_code securely if required.

    print(json.dumps(data, indent=4, ensure_ascii=False))

except requests.RequestException as error:
    print(json.dumps({
        "status": "error",
        "message": f"API request failed: {error}"
    }, indent=4))

except (ValueError, json.JSONDecodeError) as error:
    print(json.dumps({
        "status": "error",
        "message": str(error)
    }, indent=4))
Node.js 18+
const apiUrl = 'https://auth.electrocompsystem.com/api/v1/verifications';
const apiKey = 'YOUR_API_KEY';

async function fetchVerification() {
    try {
        if (!apiKey || apiKey === 'YOUR_API_KEY') {
            throw new Error('API key is not configured.');
        }

        const response = await fetch(apiUrl, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${apiKey}`,
                'Accept': 'application/json'
            },
            signal: AbortSignal.timeout(15000)
        });

        const responseText = await response.text();

        let data;

        try {
            data = JSON.parse(responseText);
        } catch {
            throw new Error(
                `API returned an invalid JSON response (HTTP ${response.status}).`
            );
        }

        if (
            response.status === 200 &&
            data.status === 'success'
        ) {
            const linkedNumber = String(data.linked_phone_number ?? '');
            const secureCode = String(data.secure_code ?? '');

            // Store linkedNumber and secureCode securely if required.
        }

        console.log(JSON.stringify(data, null, 2));

        if (!response.ok) {
            process.exitCode = 1;
        }
    } catch (error) {
        const message =
            error instanceof Error ? error.message : 'Unknown error occurred.';

        console.error(JSON.stringify({
            status: 'error',
            message: message
        }, null, 2));

        process.exitCode = 1;
    }
}

fetchVerification();
Java 11+
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class Main {

    private static final String API_URL =
        "https://auth.electrocompsystem.com/api/v1/verifications";

    private static final String API_KEY = "YOUR_API_KEY";

    public static void main(String[] args) {
        try {
            if (API_KEY.isBlank() || "YOUR_API_KEY".equals(API_KEY)) {
                throw new IllegalStateException(
                    "API key is not configured."
                );
            }

            HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(10))
                .build();

            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(API_URL))
                .timeout(Duration.ofSeconds(15))
                .header("Authorization", "Bearer " + API_KEY)
                .header("Accept", "application/json")
                .POST(HttpRequest.BodyPublishers.noBody())
                .build();

            HttpResponse<String> response = client.send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );

            int statusCode = response.statusCode();
            String responseBody = response.body();

            /*
             * For production use, parse responseBody with a JSON library
             * such as Jackson, Gson or org.json.
             *
             * When statusCode is 200 and status is "success", read:
             * linked_phone_number
             * secure_code
             */

            System.out.println(responseBody);

            if (statusCode < 200 || statusCode >= 300) {
                System.exit(1);
            }
        } catch (InterruptedException error) {
            Thread.currentThread().interrupt();

            System.err.println(
                "{\"status\":\"error\",\"message\":\"Request interrupted.\"}"
            );

            System.exit(1);
        } catch (Exception error) {
            String message = escapeJson(error.getMessage());

            System.err.println(
                "{\"status\":\"error\",\"message\":\"" + message + "\"}"
            );

            System.exit(1);
        }
    }

    private static String escapeJson(String value) {
        if (value == null) {
            return "Unknown error occurred.";
        }

        return value
            .replace("\\", "\\\\")
            .replace("\"", "\\\"")
            .replace("\r", "\\r")
            .replace("\n", "\\n");
    }
}
Download Postman collection

HTTP responses and recovery

StatusMeaningWhat to do
200Current values returnedStore them securely for the day.
401Missing, malformed or inactive API keyCheck the Bearer header or rotate the key in the Dashboard.
429Cooldown is active or another request is runningDo not retry immediately; use cached values and wait for the configured interval.
5xxTemporary server problemKeep the last known values and retry later with controlled backoff.

Production security checklist