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
- Use HTTPS only.
- Never expose API secrets in JavaScript, mobile apps or browser source.
- Configure exact hostnames, without protocol or path.
- The supplied domain is checked against the application's allowlist. Because API requests are server-to-server, this field is an assertion authenticated by the API secret, not independent proof of domain ownership.
- Use your own application's login session and CSRF protection in addition to this OTP factor.
- For production, enable email verification, account recovery, MFA for workspace owners, audit logging and operational monitoring.