# QuickAuth

> India-native authentication and WhatsApp Business messaging API. Phone OTP over SMS,
> WhatsApp and email; WhatsApp template messages and campaigns; transactional SMS.
> Base URL: https://api.quickauth.in

This file is written for AI coding assistants integrating QuickAuth into a product.
Everything below is the real API — endpoint paths, field names and response shapes are
copied from the running service, not paraphrased.

## Authentication

Every server-side endpoint takes two headers. There are no bearer tokens and no OAuth
dance for server-to-server calls.

    X-Client-Id: <your client id>
    X-Client-Secret: <your client secret>

Both come from the dashboard at https://dashboard.quickauth.in. The secret is shown once.
Never put either in client-side code: they authorise sending on the merchant's account.

Errors return HTTP 4xx/5xx with:

    { "errorCode": "INVALID_CLIENT_CREDENTIALS", "message": "...", "requestId": "..." }

`requestId` is worth logging — it is what support needs to trace a call.

## Phone OTP login — the three calls

Send a code, then check it. Nothing else is required.

### 1. POST /v1/auth/initiate

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

    → { "requestId": "cdf2deb4...", "status": "PENDING" }

  identity      required. Phone in international format, or an email address.
  identityType  MOBILE | EMAIL
  mode          OTP | OAUTH | MAGIC_LINK
  channel       SMS | WHATSAPP | EMAIL. Optional for OTP — falls back to the
                merchant's configured default.
  orderId       optional. Your own reference; /status can be queried by it.
  otpLength     optional. Overrides the account default.
  templateId    optional. Use a specific approved template.

### 2. POST /v1/auth/verify

    curl https://api.quickauth.in/v1/auth/verify \
      -H "Content-Type: application/json" \
      -H "X-Client-Id: $CLIENT_ID" -H "X-Client-Secret: $CLIENT_SECRET" \
      -d '{"requestId":"cdf2deb4...","otp":"123456"}'

    → { "verified": true, "identity": "919876543210" }

Verify server-side. A client that can call /verify can also lie about the result.

### 3. GET /v1/auth/status?requestId=... (or ?orderId=...)

Read-only. Returns the current state without consuming an attempt — useful for a
polling UI, and for reconciling a request whose response you lost.

### Fallback

If a merchant configures a fallback channel, an OTP whose primary send fails is
automatically re-sent on the fallback — including when the provider refuses the send
outright. Nothing is required from the integrator: it is account configuration, not
an API parameter.

## Transactional SMS — POST /v1/sms/send

For order updates, alerts and delivery notifications. Not for OTP: use /v1/auth
for that, so OTP and non-OTP traffic stay separately measured and separately billed.

    curl https://api.quickauth.in/v1/sms/send \
      -H "Content-Type: application/json" \
      -H "X-Client-Id: $CLIENT_ID" -H "X-Client-Secret: $CLIENT_SECRET" \
      -d '{
            "templateId": "order_shipped",
            "to": "919876543210",
            "variables": ["Rohit", "ORD-42"],
            "idempotencyKey": "order-42-shipped"
          }'

  templateId      required. A DLT-approved template on your account.
  to              required. Recipient in international format.
  variables       ordered values for the template's placeholders.
  variableValues  alternative to `variables`, keyed by name.
  senderId        optional. Overrides the account default sender.
  idempotencyKey  strongly recommended. The same key never sends twice, which
                  makes a retry after a timeout safe.

India requires DLT registration for transactional SMS. Templates must be approved
before they will send — this is a regulatory requirement, not a QuickAuth one.

## WhatsApp — POST /v1/whatsapp/messages

One template message to one recipient. Synchronous: the response tells you what
happened rather than only that it was queued.

    curl https://api.quickauth.in/v1/whatsapp/messages \
      -H "Content-Type: application/json" \
      -H "X-Client-Id: $CLIENT_ID" -H "X-Client-Secret: $CLIENT_SECRET" \
      -d '{
            "templateId": "order_shipped",
            "to": "919876543210",
            "variables": { "customer_name": "Rohit", "order_id": "ORD-42" }
          }'

    → { "messageId": 917164, "to": "919876543210", "status": "SENT",
        "providerMessageId": "wamid...." }

  templateId  required. Your QuickAuth template id.
  to          required.
  variables   keyed by the variable names your template declares.
  wabaId      optional. Pins the send to one of your WhatsApp numbers.
              Omit and routing picks.

Poll GET /v1/whatsapp/messages/{messageId}/status for the delivery outcome, or
subscribe to a webhook and be told.

Other WhatsApp endpoints:

  POST /v1/whatsapp/templates            create a template for approval
  GET  /v1/whatsapp/templates            list yours, with approval status
  GET  /v1/whatsapp/templates/{id}       one template's status and why
  POST /v1/whatsapp/campaigns            bulk send to a recipient list (async)
  POST /v1/whatsapp/messages/session     free-form reply inside the 24h window
  GET  /v1/whatsapp/health               your numbers' quality ratings

## One endpoint, any channel — POST /v1/messages/send

Sends on whatever channel the template is bound to, so a single integration can
move a message between SMS and WhatsApp without a code change.

    { "templateId": "order_shipped", "phone": "919876543210",
      "variables": { "name": "Rohit" }, "channel": "WHATSAPP" }

`channel` is optional and acts as an assertion: if it disagrees with the template's
own channel, the call is refused rather than sent on the wrong one at the wrong rate.

## Campaigns — POST /v1/marketing/initiate

Bulk sends. Returns a campaignId immediately; the send runs in the background.
Poll GET /v1/marketing/status/{campaignId}.

Use this for a recipient list. For one message, use /v1/whatsapp/messages — it
creates no campaign and answers synchronously.

## Marketing platform integrations

If you run campaigns from CleverTap or WebEngage, QuickAuth can be added there as
your WhatsApp provider. You write no code: configure the endpoint in their dashboard
and QuickAuth handles the rest, including delivery reports back to them.

  WebEngage (private BSP)   POST https://api.quickauth.in/v1/webengage/whatsapp
  CleverTap (generic)       POST https://api.quickauth.in/v1/clevertap/whatsapp

Both authenticate with the same X-Client-Id / X-Client-Secret headers, entered as
custom headers in the platform's provider configuration. Delivery reports are
configured from the QuickAuth dashboard under Webhooks.

## Webhooks

Subscribe to delivery and engagement events at dashboard.quickauth.in → Webhooks.
Events include delivery.sent, delivery.delivered, delivery.failed, message.received
and link.clicked. Payloads are signed; verify the signature before trusting one.

## Things that are easy to get wrong

- Verify OTPs server-side. Always.
- Use idempotencyKey on SMS. A timeout is not proof that nothing was sent.
- Phone numbers go in international format without a leading +, e.g. 919876543210.
- WhatsApp template variables are keyed by name; SMS template variables are ordered.
- A 200 from a send endpoint means accepted, not delivered. Delivery arrives later,
  by webhook or by polling.
- Templates must be approved before they send. Both WhatsApp and Indian SMS require it.

## Docs

  https://quickauth.in/docs               overview and quickstart
  https://quickauth.in/docs/api           authentication REST API
  https://quickauth.in/docs/sms-api       transactional SMS
  https://quickauth.in/docs/whatsapp-api  WhatsApp Business API
  https://quickauth.in/docs/integrations  CleverTap and WebEngage
  https://quickauth.in/docs/sdk/web       browser and mobile SDKs