SSoftMaji Authenticator
DEVELOPER CENTER

API documentation

Integrate SoftMaji Authenticator into any server-side application.

1. Request signing

Every API call must be signed with your application secret. Send these headers:

X-Auth-Key: YOUR_API_KEY
X-Auth-Timestamp: UNIX_TIMESTAMP
X-Auth-Nonce: 32_RANDOM_HEX_CHARACTERS
X-Auth-Signature: HMAC_SHA256_HEX

Signature message, with newline separators:

POST
/api/v1/otp/request
TIMESTAMP
NONCE
SHA256_OF_RAW_JSON_BODY

Compute HMAC-SHA256 of that exact message using your API secret. Keep the secret on your backend only. Timestamp tolerance is 5 minutes; nonce reuse is rejected.

2. Request an OTP

POST https://auth.softmaji.in/api/v1/otp/request
Content-Type: application/json

{
  "domain": "admin.example.com",
  "subject": "admin@example.com",
  "purpose": "Admin login"
}

Success response:

{
  "ok": true,
  "challenge_id": "opaque-challenge-id",
  "expires_in": 60
}

The OTP is intentionally never included in this response. The authenticated workspace owner sees it on /?page=live.

3. Verify an OTP

POST https://auth.softmaji.in/api/v1/otp/verify
Content-Type: application/json

{
  "challenge_id": "CHALLENGE_ID",
  "otp": "123456"
}

Success response:

{ "ok": true, "verified": true }

Incorrect, expired or already-used codes are rejected. A challenge can be verified only once.

4. PHP signing example

$body = json_encode($payload, JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$message = "POST\n".$path."\n".$timestamp."\n".$nonce."\n".hash("sha256", $body);
$signature = hash_hmac("sha256", $message, $apiSecret);

$headers = [
  "Content-Type: application/json",
  "X-Auth-Key: ".$apiKey,
  "X-Auth-Timestamp: ".$timestamp,
  "X-Auth-Nonce: ".$nonce,
  "X-Auth-Signature: ".$signature
];

$ch = curl_init("https://auth.softmaji.in".$path);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $body,
  CURLOPT_HTTPHEADER => $headers,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 10
]);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);

Security and domain configuration