DigiLocker Initialize API - Flutter SDK

Endpoint Overview

POST /api/v1/digilocker/initialize

Description

The DigiLocker Initialize API is the foundational endpoint for integrating the Digiboost Flutter SDK into your cross-platform mobile application. This API securely provisions an authentication session for document verification and digital identity workflows, returning a time-limited JWT token and unique client identifier required for SDK initialization. By leveraging this endpoint, organizations can enable seamless, secure, and highly customizable digital onboarding and eKYC flows within their Flutter applications across both Android and iOS platforms.

This endpoint handles the critical first step of establishing a secure session between your application and the DigiLocker ecosystem, enabling users to access and share their government-verified documents stored in DigiLocker for identity verification purposes.

Key Benefits

Enable rapid digital document verification and eKYC across Android and iOS with a single codebase

Highly customizable user experience with support for branding, language preferences, and voice assistance

Enterprise-grade security with short-lived JWT tokens (10-minute expiry) for enhanced compliance

Built-in retry mechanisms and dropout prevention features for optimized conversion rates

Use Cases

Banking & Finance

Telecom

Insurance

Streamlined digital onboarding for new banking customers with instant KYC completion

Secure loan and credit card application processing using government-verified documents

Account opening workflows with automated identity verification

Regulatory compliance for customer due diligence (CDD) requirements

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key and credentials.

Generate JWT Token: Use your API key to generate a JWT token for authentication.

Include in Requests: Add the token to the Authorization header as Bearer YOUR_JWT_TOKEN.

Different authentication tokens and base URLs are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app (for development and testing)

Production: https://kyc-api.surepass.app (for live applications)

Security Note: Never expose your JWT token or API credentials in client-side code, version control systems, or public repositories.

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token (JWT) for API authentication. Format: `Bearer YOUR_JWT_TOKEN`
Content-Type	Yes	Must be set to `application/json` for JSON request bodies

Request Body

Parameter	Type	Required	Description
data	Object	Yes	Container object for all initialization parameters
data.signup_flow	Boolean	Yes	Determines the DigiLocker flow type. Set to `true` for new users (they must provide a PIN during registration). Set to `false` for existing DigiLocker users (proceeds with login flow)
data.auth_type	String	Yes	Authentication type for SDK integration. Must be set to `"app"` for Flutter SDK integration

Example Request (Minimal Configuration)

{
  "data": {
    "signup_flow": true,
    "auth_type": "app"
  }
}

Example Request (With Webhook Integration)

{
  "data": {
    "signup_flow": true,
    "auth_type": "app",
    "webhook_url": "https://api.yourcompany.com/webhooks/digilocker/callback",
    "state": "user_session_12345",
    "send_email": true
  }
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container object for session credentials and initialization parameters
data.client_id	String	Unique client identifier for the DigiLocker session. Use this for tracking and reference
data.token	String	JWT token required for Flutter SDK initialization. This token expires in 10 minutes (600 seconds)
data.expiry_seconds	Number	Token validity duration in seconds. Typically 600.0 (10 minutes)
status_code	Integer	HTTP status code indicating request outcome (200 for successful requests)
message_code	String	Machine-readable status code. Returns `"success"` for successful initialization
message	String	Human-readable status message providing context about the request result
success	Boolean	Boolean flag indicating whether the request was processed successfully

Example Successful Response

{
  "data": {
    "client_id": "digilocker_cntWpMxWHbcvgghtyvxw",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfaWQiOiJkaWdpbG9ja2VyX2NudFdwTXhXSGJjdmdnaHR5dnh3IiwiZXhwIjoxNzM3MjA2NDAwfQ.sampleSignatureHash",
    "expiry_seconds": 600.0
  },
  "status_code": 200,
  "message_code": "success",
  "message": "Success",
  "success": true
}

Example Webhook Response

Note: This is the asynchronous response sent to your configured webhook URL after the user completes the DigiLocker authentication flow. This is separate from the API initialization response.

{
  "client_id": "digilocker_lbsfmoudALfjHnrowLCl",
  "status": "success",
  "type": "digilocker",
  "timestamp": "2026-01-17T10:30:45Z"
}

Possible Error Responses

Invalid/Expired Token

Missing Required Parameter

Invalid Parameter Value

Rate Limit Exceeded

{
  "status_code": 401,
  "message_code": "invalid_token",
  "message": "The provided authorization token is invalid or has expired",
  "success": false
}

Cause: The JWT Bearer token in the Authorization header is missing, malformed, invalid, or expired.

Resolution: Generate a fresh JWT token using your API credentials and ensure it's properly included in the Authorization header as Bearer YOUR_JWT_TOKEN.

Integration Best Practices

Security Recommendations

Always use HTTPS endpoints to protect sensitive data during transit and prevent man-in-the-middle attacks

Never expose JWT tokens, API credentials, or client secrets in client-side code, mobile app bundles, or public repositories

Implement token refresh mechanisms on your backend to generate fresh tokens for each SDK initialization

Rotate API keys and credentials regularly (recommended: every 90 days) and monitor for unauthorized access attempts

Store tokens securely using platform-specific secure storage (Keychain on iOS, KeyStore on Android)

Implement certificate pinning in your Flutter app to prevent SSL/TLS interception attacks

User Experience Guidelines

Customize the SDK with your brand logo and color scheme for a seamless, white-labeled user experience

Set appropriate retry limits (recommended: 2-3 attempts) to balance user convenience with security requirements

Use the skip_main_screen parameter strategically based on your onboarding flow complexity and user familiarity

Prefill user information when available to reduce friction and minimize data entry errors

Provide clear instructions and contextual help within your app before launching the DigiLocker SDK flow

Implement proper loading states and error handling to maintain a smooth user experience during token generation

Code Samples

cURL

Python

Node.js

Flutter/Dart

Flutter SDK Integration Guide

Quick Start with Sample Application

A complete Flutter sample application demonstrating the integration of Surepass DigiLocker Flutter SDK is available for reference and testing.

Prerequisites

Flutter SDK 3.10.4 or higher

Dart SDK 3.10.4 or higher

Android Studio / Xcode (for device deployment)

Valid Surepass API token from Surepass Dashboard

Sample App Installation

Clone the Repository

Install Dependencies

Run the Application

Using the Sample App

Launch the app on your device or emulator

Select environment (Sandbox or Production)

Enter your API token from Surepass Dashboard

Click "Get Started" to begin the DigiLocker verification flow

View results after verification completes

SDK Integration in Your Project

To integrate the DigiLocker Flutter SDK into your own Flutter application, add the following dependency to your pubspec.yaml file:

Note: Replace <USERNAME> and <PAT> with your GitHub username and Personal Access Token.

After adding the dependency, run:

No additional setup is required. The SDK will be fetched automatically.

Platform Configuration

Android Requirements

Minimum SDK: 28

Configuration is handled automatically by the SDK

iOS Requirements

Minimum iOS: 15.0

Required permissions are pre-configured in the SDK's Info.plist

Sample Project Structure

digilocker-flutter-sample/
├── lib/
│   └── main.dart          # Main application code
├── android/               # Android configuration
├── ios/                   # iOS configuration
├── assets/                # App assets
└── pubspec.yaml           # Dependencies

Troubleshooting SDK Integration

SDK Not Found

Build Errors

API Token Issues

Issue: SDK dependency cannot be resolved

Solutions:

Run flutter pub get to fetch dependencies

Verify your internet connection is stable

Ensure the SDK repository URL is correct and accessible

Check that your GitHub credentials (username and PAT) are valid

For additional support with SDK integration, contact techsupport@surepass.app.

Related APIs

DigiLocker Document Fetch API: Retrieves verified documents from DigiLocker after successful user authentication and consent

DigiLocker Verification API: Validates the authenticity and integrity of documents retrieved from the DigiLocker system

Digiboost Session Status API: Monitors and tracks the real-time status of an ongoing Digiboost verification session

DigiLocker eSign API: Enables digital signing of documents using DigiLocker eSign infrastructure

Aadhaar eKYC API: Performs electronic Know Your Customer verification using Aadhaar authentication

Compliance and Legal Considerations

User Consent: Always obtain explicit, informed consent from users before initiating any KYC, document verification, or data collection process. Maintain audit logs of consent records.

Data Privacy Regulations: Ensure compliance with applicable data protection laws including the Information Technology Act 2000, GDPR (for EU users), and other regional privacy regulations.

Data Retention: Store and process user data securely. Do not retain sensitive tokens, credentials, or personal documents longer than necessary for the intended purpose. Implement data deletion policies.

DigiLocker Terms: Comply with DigiLocker's terms of service and usage policies. Do not misuse or attempt to circumvent DigiLocker's security measures.

KYC Regulations: Adhere to RBI (Reserve Bank of India) KYC guidelines, PMLA (Prevention of Money Laundering Act) requirements, and sector-specific regulatory mandates.

Audit Trail: Maintain comprehensive audit logs of all verification activities, including timestamps, user identifiers, and verification outcomes for regulatory compliance and dispute resolution.

Environment Configuration

Environment	Base URL	Purpose	Token Validity
Sandbox (UAT)	`https://sandbox.surepass.app`	Development, testing, and integration	10 minutes (600 seconds)
Production	`https://kyc-api.surepass.app`	Live production applications	10 minutes (600 seconds)

Important Notes:

Use separate API credentials for sandbox and production environments

Test thoroughly in the sandbox environment before deploying to production

Monitor token expiry and implement proper refresh mechanisms

Production credentials should be stored securely and never committed to version control

Response Handling Best Practices

Token Management: Store the received token securely and use it immediately for SDK initialization. Implement token expiry handling (10-minute validity).

Client ID Tracking: Store the client_id for session tracking, analytics, and support purposes. This identifier can be used to query session status via other APIs.

Error Handling: Implement comprehensive error handling for all possible HTTP status codes (400, 401, 403, 429, 500, etc.) and display user-friendly error messages.

Webhook Processing: If using webhooks, implement proper signature verification and idempotency handling to prevent duplicate processing of callback events.

Retry Logic: For network failures or temporary errors (5xx status codes), implement exponential backoff retry logic with a maximum retry limit.

Logging and Monitoring: Log all API interactions (excluding sensitive data like tokens) for debugging, monitoring, and analytics purposes.

This documentation provides enterprise-grade guidance for integrating the DigiLocker Initialize API with the Flutter SDK, ensuring secure, compliant, and user-friendly digital identity verification workflows.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

⭐️ Initialize via Flutter SDK

DigiLocker Initialize API - Flutter SDK#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request (Minimal Configuration)#

Example Request (With Webhook Integration)#

Response Parameters#

Example Successful Response#

Example Webhook Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Flutter SDK Integration Guide#

Quick Start with Sample Application#

Prerequisites#

Sample App Installation#

Using the Sample App#

SDK Integration in Your Project#

Platform Configuration#

Android Requirements#

iOS Requirements#

Sample Project Structure#

Troubleshooting SDK Integration#

Environment Configuration#

Response Handling Best Practices#

Request

Responses