Registration

This guide provides everything you need to integrate the ABHA SDK into your application for Create ABHA, Login with ABHA flows into your healthcare applications. It provides:

Create ABHA: Create a new ABHA using Mobile or Aadhaar.
Login with ABHA: Login to your exisiting ABHA using PHR Address, ABHA number, Aadhaar number or Mobile number.

Implementation Example

Add the following HTML and script tags to your webpage:

For staging/dev environments, replace the SDK URLs with:

JS: https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/js/abha.js
CSS: https://unpkg.com/@eka-care/abha-stg/dist/sdk/abha/css/abha.css

<!DOCTYPE html>
<html>
  <head>
    <title>ABHA SDK Integration</title>

    <!-- Include ABHA SDK CSS -->
    <link
      rel="stylesheet"
      href="https://unpkg.com/@eka-care/abha/dist/sdk/abha/css/abha.css"
    />
  </head>
  <body>
    <h1>ABHA SDK Demo</h1>

    <!-- Mount Button -->
    <button class="button" onclick="mountABHASDK()">Mount SDK</button>

    <!-- Container for ABHA SDK -->
    <div id="sdk_container"></div>

    <!-- Include ABHA SDK JS -->
    <script
      type="module"
      src="https://unpkg.com/@eka-care/abha/dist/sdk/abha/js/abha.js"
    ></script>

    <script>
      function mountABHASDK() {
        window.initAbhaApp({
          containerId: "sdk_container",
          clientId: 'ext',
        
         // Pass access token and oid
          data: {
            accessToken: "<your_access_token>", // Pass the access token you have
            oid: "<patient_oid>", // Pass OID of the patient
            hipId: "<available_HFR_ID>", // Pass the HFR ID you have
            orgIconUrl: "<url_of_your_org_logo>", // Pass the url of the logo of your organisation for ex https://cdn.eka.care/vagus/cl5jgf0u500070shaetqw0r5l.png
            linkToOrgIcon: "<url_of_image_to_link_abha_to_your_org>", // Pass the url of an image which depicts linking abha to your organisation for ex https://cdn.eka.care/vagus/cm6agrs5000090tfwfz984x5b.webp
            skipABHAEnable: "<boolean_value_here>" // Pass boolean as true if you want Skip ABHA button to be enabled on login screen
          },

          // Success callback
          onSuccess: (params) => {
            console.log("ABHA Registration flow completed successfully:", params);
            
            // Example: Store ABHA data in your app
            if (window.EkaAbha) {
              window.EkaAbha.onAbhaSuccess(JSON.stringify(params));
            }
          },

          // Error callback
          onError: (params) => {
            console.error("ABHA SDK failed:", params);

            // Example: Store ABHA data in your app
            if (window.EkaAbha) {
              window.EkaAbha.onAbhaFailure(JSON.stringify(params));
            }
          },

          // Abha Close callback
          onAbhaClose: () => {
            console.log("ABHA SDK closed");
          },

          // Skip ABHA callback
          onSkipAbha: (params) => {
            console.log("ABHA flow SKIPPED:", params);
          },

        });
      }
    </script>
  </body>
</html>

Core Functions

1. initAbhaApp

Initializes and renders the ABHA SDK in your specified container. Parameters:

Name	Type	Required	Description
`containerId`	`string`	✅	The HTML element ID where the SDK will mount.
`clientId`	`string`	✅	Provide clientId as `ext`.
`data`	`{` `accessToken: string;` `oid?: string;` `hipId?: string;` `orgIconUrl?: string;` `linkToOrgIcon?: string;` `skipABHAEnable?: boolean;` `}`	⚙️ Optional	Configuration data for initializing the ABHA flow. - accessToken: Pass the access token you have generated from Connect Login API without the word `Bearer`. - oid: Pass the OID of the patient if available. - hipId: Pass the HFR ID you have. - orgIconUrl: Public CDN URL of the logo of your organisation url should start with https://. Example - linkToOrgIcon: Public CDN URL of the icon representing “Link ABHA to your organisation” url should start with https://. Example - skipABHAEnable: Pass the boolean as true if you want Skip ABHA button to be enabled on login screen. `keys with ? are optional.`
`onSuccess`	`(params: TOnAbhaSuccessParams) => void`	✅	Triggered when the user successfully creates or logs in to ABHA.
`onError`	`(params: TOnAbhaFailureParams) => void`	✅	Triggered when an error occurs during the ABHA flow.
`onAbhaClose`	`() => void`	✅	Triggered when SDK closes.
`onSkipAbha`	`(params: TOnSkipABHA) => void`	⚙️ Optional	Triggered if the ABHA flow is skipped.

Example:

window.initAbhaApp({
  containerId: "sdk_container",
  data: {
    accessToken: "your_access_token_here",
    oid: "patient_oid_here",
    hipId: "available HFR ID",
    linkToOrgIcon: "url_of_image_to_link_abha_to_your_org",
    skipABHAEnable: "boolean_value_here"
  },
  onSuccess: (params) => {
    console.log("ABHA created successfully!", params);
  },
  onError: (error) => {
    console.error("ABHA flow failed:", error);
  },
  onAbhaClose: (error) => {
    console.error("ABHA SDK closed");
  },
  onSkipAbha: (params) => {
    console.log("ABHA flow skipped by user:", params);
  },

});

Callback Parameters

onSuccess Callback

The onSuccess callback is triggered when the ABHA flow completes successfully. It returns verified user details and tokens, which can be used to log in or continue the user’s session. Callback Signature:

onSuccess: (params: TOnAbhaSuccessParams) => void;

Type Definitions

type TOnAbhaSuccessParams = {
  response: TAuthVerifyV2Response;
};

type TAuthVerifyV2Response = {
  skip_state: number;
  method: AUTH_METHOD;
  data?: {
    tokens: {
      sess: string;
      refresh: string;
    };
    profile: TProfileRecord;
  };
  txn_id: string;
  error?: {
    code: number;
    message: string;
  };
};

enum AUTH_METHOD {
  EMAIL = 1,
  MOBILE = 2,
  ABHA = 7,
}

type TProfileRecord = {
  fln: string;
  fn: string;
  mn?: string;
  ln?: string;
  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
  dob?: string;
  mobile?: string;
  email?: string;
  uuid?: string;
  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
  pic?: string;
  as?: string;
  "dob-valid"?: boolean;
  "is-d"?: boolean;
  "is-d-s"?: boolean;
  "is-p"?: boolean;
  oid: string;
  at: string;
  type?: 1 | 2 | 3 | 4 | 5 | 6;
  "health-ids"?: Array<string>;
  abha_number?: string;
  kyc_verified?: boolean;
};

Parameters

Key	Type	Description
`response`	`TAuthVerifyV2Response`	The complete ABHA verification response, containing session tokens, user profile, and transaction details.

Example:

const onSuccess = (params) => {
  console.log("ABHA Success:", params.response);

  const abhaNumber = params.response.data?.profile?.abha_number;
  const userName = params.response.data?.profile?.name;

  alert(`Welcome ${userName}! Your ABHA Number: ${abhaNumber}`);

  // Optionally pass data to native bridge if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaSuccess(JSON.stringify(params));
  }
};

onError Callback

The onError callback is triggered whenever an ABHA flow fails or is interrupted. It provides details about the failure through structured parameters, allowing you to handle or forward the error appropriately (for example, to native apps or monitoring tools). Callback Signature:

onError: (params: TOnAbhaFailureParams) => void;

Type Definitions

type TOnAbhaFailureParams = {
  error?: string;
  response?: TAuthVerifyV2Response;
};

type TAuthVerifyV2Response = {
  skip_state: number;
  method: AUTH_METHOD;
  data?: {
    tokens: {
      sess: string;
      refresh: string;
    };
    profile: TProfileRecord;
  };
  txn_id: string;
  error?: {
    code: number;
    message: string;
  };
};

enum AUTH_METHOD {
  EMAIL = 1,
  MOBILE = 2,
  ABHA = 7,
}

type TProfileRecord = {
  fln: string;
  fn: string;
  mn?: string;
  ln?: string;
  gen?: "M" | "F" | "O" | "U" | undefined; // 'male' | 'female' | 'other' | 'unknown'
  dob?: string;
  mobile?: string;
  email?: string;
  uuid?: string;
  bloodgroup?: "" | "A+" | "A-" | "B+" | "B-" | "O+" | "O-" | "AB+" | "AB-";
  pic?: string;
  as?: string;
  "dob-valid"?: boolean;
  "is-d"?: boolean;
  "is-d-s"?: boolean;
  "is-p"?: boolean;
  oid: string;
  at: string;
  type?: 1 | 2 | 3 | 4 | 5 | 6;
  "health-ids"?: Array<string>;
  abha_number?: string;
  kyc_verified?: boolean;
};

Parameters

Key	Type	Description
`error`	`string?`	Short description of the failure or error message.
`response`	`TAuthVerifyV2Response?`	Partial or full API response object returned from ABHA services.

Example:

const onError = (params) => {
  console.error("ABHA Error:", params);

  if (params.response?.error?.code === 1001) {
    alert("Authentication failed. Please try again.");
  } else if (params.error === "NETWORK_ERROR") {
    alert("Please check your internet connection.");
  } else {
    alert("Something went wrong. Please retry.");
  }

  // Forward the error to native handler if available
  if (window.EkaAbha) {
    window.EkaAbha.onAbhaFailure(JSON.stringify(params));
  }
};

onAbhaClose Callback

The onAbhaClose callback is triggered when the ABHA SDK flow gets closed. Callback Signature:

onAbhaClose: () => void;

Example:

const onAbhaClose = () => {
  console.log("ABHA SDK Closed");
};

onSkipAbha Callback

The onSkipAbha callback is triggered when the ABHA SDK flow is skipped. The callback is functional when skipABHAEnable is set to true in the data parameter while initializing the SDK. Callback Signature:

onSkipAbha: (params: TOnSkipABHA) => void;

Example:

const onSkipAbha = (params) => {
  console.log("ABHA SDK Skipped:", params);
};

Type Definitions

 type IdentifierType = "mobile" | "aadhaar_number" | "abha_number" | "phr_address";

 type TOnSkipABHA = {
  identifier?: string;
  identifier_type?: IdentifierType[]; // No default value here
};

Parameters

Key	Type	Description
`identifier`	`string?`	It will be login identifier value filled by user.
`identifier_type`	`IdentifierType[]?`	It will be type of login identifier.

Suggest Handling

Always log the full error response (params) for debugging.
Display friendly error messages for known error.code values.
If params.response is present, inspect response.error.message for more detail.
If integrating with native apps, forward the serialized error object:

window.EkaAbha.onAbhaFailure(JSON.stringify(params));

Container Styling

Ensure your container has sufficient space:

<div
  id="sdk_container"
  style="width: 100%; height: 600px; border: 1px solid #ddd;"
></div>

Troubleshooting

Common Issues

1. SDK Not Rendering

Problem: Nothing appears in the container. Solution:

Ensure containerId matches an existing HTML element.
Verify the SDK JS and CSS are correctly loaded.
Check browser console for errors.

2. APIs Not Being Called

Problem: API requests are not triggered after the SDK is mounted. Solution:

Ensure that the accessToken is passed correctly (do not include the Bearer prefix) and that the token has not expired.
To prevent CORS-related issues, ensure that your domain is whitelisted.

3. Callback Not Triggered

Problem: onSuccess, onError, onKYCSuccess, onConsentSuccess, onAbhaClose isn’t firing. Solution:

Make sure callbacks are passed as valid functions.
Avoid race conditions (e.g., calling before SDK fully loads).

4. Styling Issues

Problem: SDK content appears misaligned or clipped. Solution:

Give your container a fixed height (e.g., 600px).
Ensure no parent element uses overflow: hidden.

Authorization

End-to-End Encryption

Connect

HealthAI

Medical Database

ABDM Connect

Doctor Tool

Medical Knowledge-bases

Medical Records

User App

Implementation Example

Core Functions

1. initAbhaApp

Callback Parameters

onSuccess Callback

onError Callback

onAbhaClose Callback

onSkipAbha Callback

Container Styling

Troubleshooting

Common Issues

1. SDK Not Rendering

2. APIs Not Being Called

3. Callback Not Triggered

4. Styling Issues

​ABHA SDK - Login or Create

​Implementation Example

​Core Functions

​1. initAbhaApp

​Callback Parameters

​onSuccess Callback

​onError Callback

​onAbhaClose Callback

​onSkipAbha Callback

​Container Styling

​Troubleshooting

​Common Issues

​1. SDK Not Rendering

​2. APIs Not Being Called

​3. Callback Not Triggered

​4. Styling Issues

ABHA SDK - Login or Create

Implementation Example

Core Functions

1. initAbhaApp

Callback Parameters

onSuccess Callback

onError Callback

onAbhaClose Callback

onSkipAbha Callback

Container Styling

Troubleshooting

Common Issues

1. SDK Not Rendering

2. APIs Not Being Called

3. Callback Not Triggered

4. Styling Issues