OVSE Init

API reference

curl -X POST "https://__playground__/verification/v1/ovse/init" \  -H "Content-Type: application/json" \  -d '{}'

{
  "session_id": "ovse_sess_abc123",
  "txn": "txn_xyz789",
  "intent_url": "https://getintent.uidai.gov.in/...",
  "get_intent_url": "https://getintent.uidai.gov.in/...",
  "qr_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "web_intent_url": "intent:#Intent;...",
  "ios_web_to_app_url": "pehchaan://in.gov.uidai.pehchan?request=...",
  "app_link": "https://...",
  "launch_url": "https://verify.test.getkwikid.com/verification/v1/ovse/launch/ovse_sess_abc123?token=...",
  "expires_at": 1749456000,
  "jwt": "eyJhbGciOiJIUzI1NiIs..."
}

{
  "detail": {},
  "message": "string"
}

{
  "detail": {},
  "message": "string"
}

{
  "error": "string"
}

Overview

OVSE Init is the first server-side call for Aadhaar offline verification via the UIDAI Aadhaar App. Your backend sends POST /verification/v1/ovse/init with a Bearer token scoped to verify-aadhaar-ovse. The response includes launch targets for both cross-device QR and same-device Web to App flows in a single call.

After the resident completes authentication in the Aadhaar App, UIDAI posts an SD-JWT to KwikID. Your backend then polls OVSE Status (or receives a webhook when configured) for normalized identity fields.

Why Init exists: API token stays on the server; the resident only follows QR codes or deeplinks the API returns.

Key features

• Single init, dual flow: One response serves agent-desktop QR and mobile same-device deeplinks.
• Optional qr_base64: PNG QR for cross-device display when include_qr is true (default).
• Optional webhook_url: HTTPS push after successful SD-JWT decode instead of polling only.
• Optional client_reference_id: Your correlation id echoed in status and webhook payloads.

Implementation

Prerequisites

1. API token with AppSecure scope verify-aadhaar-ovse.
2. Mobile device with the UIDAI Aadhaar App installed (same-device flow), or a screen to display the QR (cross-device flow).

Step 1: Call Init from your backend

Headers

• Authorization: Bearer <token>. Required. Scope must include verify-aadhaar-ovse.

POST /verification/v1/ovse/init HTTP/1.1
Host: <verification-api-base-url>
Authorization: Bearer <token>
Content-Type: application/json

{
  "client_reference_id": "session-12345",
  "include_qr": true,
  "webhook_url": "https://your-app.example.com/webhooks/ovse"
}

Use your real base URL for the Verification API (production or sandbox from KwikID).

Step 2: Present the flow to the resident

On 200 OK, note session_id, txn, and the launch fields.

Do: Keep session_id and txn server-side for status polling. Do not: Expose your Bearer token in client-side JavaScript.

Step 3: Poll status or wait for webhook

When the resident finishes Aadhaar authentication:

• Poll OVSE Status with session_id until session_status is completed, failed, or expired.
• Or rely on your webhook_url when configured.

End-to-end flow

Error handling

Security notes

• Never expose the Verification API token in client-side JavaScript or mobile apps that users control.
• launch_url includes a one-time token query param; treat it as sensitive and time-bound.
• Responses contain session identifiers; log correlation ids only, not full PII from later status calls.

Benefits

• Consent-based offline Aadhaar verification without live CIDR lookup.
• One init call covers agent-assisted QR and self-serve same-device journeys.
• OKYC-compatible identity fields after successful decode.

Next steps

• OVSE Status
• Verification API index