Log in to an existing ABHA - Eka Developer Platform APIs

In short

Log in by ABHA address, mobile or Aadhaar, each with an OTP.
Every route ends with skip_state set to abha_end and the patient’s oid.
Each call takes the txn_id from the most recent response.

When to use this

The patient already has an ABHA and can identify it by one of: their ABHA address, their Aadhaar number, or a mobile number. They authenticate with an OTP. All three routes end with skip_state set to abha_end and give you the patient’s oid. Pick the route from what the patient can offer:

ABHA address (shyam@abdm): two calls, init and verify.
Mobile number: init, verify, then pick one of the ABHA addresses on that mobile.
Aadhaar number: init, verify, then auto-login into one of the ABHA addresses on that Aadhaar.

If the patient has no ABHA, use Create an ABHA with Aadhaar OTP or Create an ABHA address with mobile OTP.

Before you start

A client access token, sent as a Bearer token on every call. See Client login.
Your facility onboarded as a Health Information Provider (HIP).
In hand: the patient’s ABHA address, Aadhaar number or mobile number, and access to the phone that receives the OTP.

Sequence

Steps

Check the login methods (ABHA address route)

Send abha_address to Search Auth Methods. The response carries auth_methods and blocked_methods. Offer the patient only methods in auth_methods.

Search by mobile (search route, optional)

Send mobile to Search. It returns KYC-verified ABHA profiles on that mobile in profiles, each with an index and abha_address, plus a txn_id. The patient picks one. Pass its index as identifier and the txn_id to the next step with method set to search.

Send the OTP

Send method, identifier and otp_system to Generate OTP:

ABHA address route: method is phr_address, identifier is the ABHA address.
Mobile route: method is mobile, identifier is the mobile number.
Aadhaar route: method is aadhaar_number, identifier is the Aadhaar number.
method also accepts abha_number.

otp_system is abdm or aadhaar. The response carries txn_id and a hint. Keep txn_id; every later call takes the txn_id from the most recent response.

Verify the OTP

Send txn_id and otp to Verify OTP. The response carries skip_state, abha_profiles, profile, eka.oid and a new txn_id. Branch on the route and skip_state:

ABHA address route: skip_state is abha_end. Login is complete. Stop here.
Mobile route: abha_profiles lists the ABHA addresses on the mobile. The patient picks one. Go to “Complete the mobile login”.
Aadhaar route: skip_state is abha_create. If abha_profiles is non-empty, the patient picks one and you go to “Complete the Aadhaar login”. If it is empty, the patient has no ABHA address on this Aadhaar; create one.

Complete the mobile login

Send txn_id and the chosen address as phr_address to Login. The response carries skip_state set to abha_end, profile and eka.oid.

Complete the Aadhaar login

Send txn_id and the chosen abha_address to Auto Login. The response carries skip_state set to abha_end, profile, eka.oid, token and refresh_token.

Whether login also opens the patient’s ABHA Gateway session is not yet confirmed; the session overview names only registration and creation. When a session expires, renew it with Hold the ABHA Gateway session rather than logging in again.

State you must persist

Field	From	Keep	For
`txn_id`	The latest response in this workflow	Until login completes	Every call in this workflow
`eka.oid`	The call that returns `abha_end`	Permanently, on the patient record	The `X-Pt-Id` header or `oid` query on every later call for this patient
`profile.abha_address`	The call that returns `abha_end`	Permanently, on the patient record	Care context linking, gateway session
`profile.abha_number`	The call that returns `abha_end`	Permanently, on the patient record, when present	ABHA card, later logins
`token`, `refresh_token`	Auto Login	Not documented	Not documented

When it fails

Which of these codes each call returns is not yet confirmed. The codes come from the errors page, matched by meaning. Log the code you actually receive.

Error responses carry code, error and source_error. source_error.code holds codes such as MIS-1013. See Error codes.

Situation	Code	Do
Wrong OTP	`MIS-1013`	Ask the patient to re-enter the OTP.
Too many OTP requests or wrong attempts	`ABDM-1100`	Tell the patient to try again in 30 minutes.
Patient blocked	`ABDM-1027`	Tell the patient to try again after 24 hours.
No ABHA found for the identifier	`ABDM-1110`, `ABDM-1012`	Offer to create an ABHA instead.
Invalid ABHA number	`ABDM-1013`	Ask the patient to check the number.
Mobile or Aadhaar not found	`ABDM-1111`, `ABDM-1112`	Ask the patient to check it, or try another route.
Method not allowed for this ABHA	`ABDM-1113`, `ABDM-1114`, `ABDM-1115`	Offer a method from `auth_methods` in Search Auth Methods.
Expired or unknown transaction	`ABDM-1017`, `MIS-1026`	Start again from Generate OTP.
Too many requests	`ABDM-1022`	Back off and retry.
ABDM or a dependent service is down	`ABDM-1019`, `ABDM-1024`, `ABDM-1004`	Retry later.

Test it

The testing page has the sandbox base URL, credentials and the happy path for every journey. Use an ABHA you created on sandbox through one of the create workflows.

ABHA address route: Search Auth Methods, Generate OTP with phr_address, Verify OTP returns abha_end and eka.oid.
Mobile route: Generate OTP with mobile, Verify OTP, Login with one address from abha_profiles returns abha_end.
Aadhaar route: Generate OTP with aadhaar_number, Verify OTP returns abha_create with a non-empty abha_profiles, Auto Login returns abha_end.
The eka.oid from login equals the one stored when the ABHA was created.
Wrong OTP once: MIS-1013. Record the code you receive; the expected code is not confirmed.
Unknown ABHA address on Search Auth Methods: an error from the failure table.

​In short

​When to use this

​Before you start

​Sequence

​Steps

​State you must persist

​When it fails

​Test it

In short

When to use this

Before you start

Sequence

Steps

State you must persist

When it fails

Test it