Developers

Authentication

Two ways to authenticate: an API key for machine access, or a JWT for dashboard sessions.

API key (recommended for servers)

Send your key in the X-MahadDoc-API-Key header.

curl https://api.mahadocr.com/v1/documents \
  -H "X-MahadDoc-API-Key: mk_live_YOUR_KEY"

Bearer token (dashboard sessions)

Sign-in returns a short-lived access token and a refresh token. Accounts with a verified phone complete a WhatsApp one-time code first.

curl -X POST https://api.mahadocr.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

# -> { "otp_required": true, "pre_token": "..." }   (when WhatsApp 2FA is on)
# -> { "token": "...", "refresh_token": "..." }     (otherwise)

Failure responses

401 — missing or invalid credentials
403 — email and phone verification required, account suspended, or insufficient permission
429 — rate limit or monthly quota reached