REST API reference

Every QuickAuth feature is reachable over plain HTTPS — handy when you’re on an unsupported stack, doing server-to-server orchestration, or just want to curl-test before you wire the SDK.

Base URL

https://api.quickauth.in

All endpoints accept and return application/json.

Authentication

Three header schemes depending on which surface you’re hitting:

Conventions

• All timestamps are ISO 8601 UTC.
• Error responses have shape { errorCode, message } with the matching HTTP status — errorCode is an UPPER_SNAKE constant (see Error codes).
• POST /v1/auth/initiate is rate-limited per identity per hour (default 10/hour, configurable per merchant). Over the limit returns 429 RATE_LIMIT_EXCEEDED.

Direct OTP API (server-to-server)

The raw server endpoints — authenticate with X-Client-Id + X-Client-Secret. Use these when you send and verify OTPs entirely from your own backend (no SDK). This is the pair behind a typical curl integration.

curl https://api.quickauth.in/v1/auth/initiate \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: qc_xxx" \
  -H "X-Client-Secret: qa_secret_yyy" \
  -d '{
    "identity":     "+919876543210",
    "identityType": "MOBILE",
    "mode":         "OTP",
    "channel":      "WHATSAPP"
  }'

Allowed values

curl https://api.quickauth.in/v1/auth/verify \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: qc_xxx" \
  -H "X-Client-Secret: qa_secret_yyy" \
  -d '{
    "requestId": "req-abc123",
    "otp":       "123456"
  }'

Session

curl https://api.quickauth.in/v1/sdk/session \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: qa_client_xxx" \
  -H "X-Client-Secret: qa_secret_yyy" \
  -d '{"scope":"sdk"}'

OTP

POST /v1/sdk/auth/initiate
Content-Type: application/json
X-Public-Key: qa_live_***
Idempotency-Key: <uuid>

{
  "phone":      "+919876543210",
  "channel":    "auto",            // "auto" | "sms" | "whatsapp"
  "template":   "login_otp",       // optional, defaults to your default template
  "deviceInfo": {                  // optional, used for trusted-device / OneTap
    "platform":  "ios",
    "model":     "iPhone 14",
    "osVersion": "18.2",
    "appVersion":"3.4.1",
    "locale":    "en-IN"
  }
}

POST /v1/sdk/auth/verify
Content-Type: application/json
Authorization: Bearer <sdk-session-token>
Idempotency-Key: <uuid>

{
  "sessionId": "qas_5fA2…",
  "code":      "123456"
}

curl 'https://api.quickauth.in/v1/auth/status?requestId=req_8h3k…' \
  -H 'X-Client-Id: qa_client_***' \
  -H 'X-Client-Secret: qa_secret_***'

authStatus values

deliveries carries one entry per send attempt, so a fallback shows up as two rows against the same requestId — the WhatsApp attempt and the SMS that followed it. Each entry’s deliveryStatus is one of PENDING, SENT, DELIVERED, READ, FAILED or SKIPPED.

Sending the OTP over WhatsApp

There is no separate WhatsApp endpoint. WhatsApp is a channel on the same /v1/auth/initiate call — the request body, the requestId you get back, /v1/auth/verify and /v1/auth/status are identical whichever channel carried the code. Switching channel is a one-field change, not an integration.

curl -X POST 'https://api.quickauth.in/v1/auth/initiate' \
  -H 'Content-Type: application/json' \
  -H 'X-Client-Id: qa_client_***' \
  -H 'X-Client-Secret: qa_secret_***' \
  -d '{
    "identity": "+919876543210",
    "identityType": "MOBILE",
    "mode": "OTP",
    "channel": "WHATSAPP"
  }'

Attribution

Webhooks

Configure a webhook URL on the dashboard. Events you’ll receive:

Errors

Every failure returns the same envelope, whichever endpoint produced it. The errorCode is the stable part — branch on it, not on the message, which is written for a human reading a log and may be reworded.

{
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "message":   "Rate limit exceeded. Try again later.",
  "requestId": "req_8h3k…"
}

requestId is present when the failure happened against a known transaction and is null otherwise — quote it to support and we can find the exact send.

HTTP status codes

Error codes

SDK quickstart from API

If you’ve worked through this page directly, the SDK pages give you the same calls wrapped with native idioms, auto-fill helpers, and consent plumbing. Pick a stack from the docs home.