DigiLocker Init

API reference

curl -X POST "https://__mock__/verification/v2/digilocker/init" \  -H "Content-Type: application/json" \  -d '{}'

{
  "redirection_url": "https://verify.test.getkwikid.com/verification/v2/digilocker/redirect?redirection_url=aHR0cHM6Ly9hcGkuZGlnaXRhbGxvY2tlci5nb3YuaW4vcHVibGljL29hdXRoMi8xL2F1dGhvcml6ZT9jbGllbnRfaWQ9RjM5Njk3MDQmc3RhdGU9YmFzaWMmZGxfZmxvdz1zaWdudXAmcmVzcG9uc2VfdHlwZT1jb2RlJnJlZGlyZWN0X3VyaT1odHRwczovL3ZlcmlmeS50ZXN0LmdldGt3aWtpZC5jb20vdmVyaWZpY2F0aW9uL3YyL2RpZ2lsb2NrZXIvY2FsbGJhY2smZGxfZmxvdz1zaWdudXA=&client_id=a3dpa2lkLWRldg==&authorization=QmVhcmVyIGZKSmhrMDNfNTE3Y3BCNmduMThMRnJIYVJoQnlZdDEzWTg4ZFAyMFVzeWZxc0RmOVZXaF9saE5ReHQxMm56amZnR1JYeWdqQzFURmd5MFNURUxSSlZmSHRxYTk0WDdYTjdzaVdVb1d3"
}

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

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

{
  "error": "string"
}

Overview

Init is the first server-side call: your backend sends POST /verification/v2/digilocker/init with a Bearer token. The response includes redirection_url. Send the end user to that URL (same tab or new window). KwikID runs the hosted DigiLocker OAuth steps; when finished, the user is sent to your callback_url (request body) or your account default if KwikID configured one.

Why Init exists: API token stays on the server; user only follows HTTPS links the API returns.

Key features

• Bearer auth: Standard Authorization: Bearer <token> from the KwikID dashboard (or how your project issues API access).
• Optional callback_url: Override per request, or rely on default agreed with KwikID.
• Optional handshake_id: Your own ID to correlate this journey with your session or database row.

Implementation

Prerequisites

1. API token with permission to use DigiLocker verification (same token model as other Verification APIs).
2. DigiLocker onboarding completed with KwikID (partner app registration and callback defaults where applicable).

Step 1: Call Init from your backend

Headers

• Authorization: Bearer <token>. Required. Missing header typically yields 400 with {"error": "Authorization token is required."}.

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

{
  "handshake_id": "session-12345",
  "callback_url": "https://your-app.example.com/digilocker/callback"
}

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

Step 2: Use redirection_url

On 200 OK:

{
  "redirection_url": "https://..."
}

Do: Redirect the user (HTTP 302/303) or open redirection_url in the browser. Do not: Parse or reconstruct this URL; treat it as an opaque, sensitive string (may embed session context). Do not: Call Init from a public front-end with your API token.

Step 3: After DigiLocker

When the flow completes, call the other DigiLocker operations using the AccessToken pattern documented on each endpoint, for example:

• Get Aadhaar XML data
• Get issued files
• Get XML (PAN, Aadhaar, etc.)

End-to-end flow

Error handling

Security notes

• Never expose the Verification API token in client-side JavaScript or mobile apps that users control.
• redirection_url is not for logging in plain text in analytics or support tickets.
• Use HTTPS for callback_url in production.

Benefits

• Token stays on the server.
• Per-request callback_url when you need different return URLs per product flow.
• handshake_id for your own bookkeeping.

Next steps

• Get Aadhaar XML data
• Get issued files
• Get XML (PAN, Aadhaar, etc.)
• Verification API index