> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Log in to an existing ABHA

> Log a patient in to an ABHA they already hold, by ABHA address, Aadhaar or mobile.

## 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](https://developer.eka.care/docs/hie-cm/workflows/create-abha-aadhaar-otp.md) or [Create an ABHA address with mobile OTP](https://developer.eka.care/docs/hie-cm/workflows/create-abha-mobile-otp.md).

## Before you start

* A client access token, sent as a Bearer token on every call. See [Client login](https://developer.eka.care/api-sdk/auth/client-login.md).
* 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

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient's phone
  opt ABHA address route, check which methods are allowed
    App->>Eka: POST /abdm/na/v1/profile/login/methods
  end
  opt Search route, find KYC-verified ABHAs by mobile
    App->>Eka: POST /abdm/v1/profile/search
  end
  App->>Eka: POST /abdm/na/v1/profile/login/init
  Eka-->>Patient: OTP
  App->>Eka: POST /abdm/na/v1/profile/login/verify
  alt ABHA address route
    Note over App,Eka: skip_state is abha_end, login complete
  else Mobile route
    App->>Eka: POST /abdm/na/v1/profile/login/phr
  else Aadhaar route
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/auto-login
  end
```

## Steps

**1. Check the login methods (ABHA address route)**

Send `abha_address` to [Search Auth Methods](https://developer.eka.care/api-sdk/hie-cm/login/methods.md). The response carries `auth_methods` and `blocked_methods`. Offer the patient only methods in `auth_methods`. 

**2. Search by mobile (search route, optional)**

Send `mobile` to [Search](https://developer.eka.care/api-sdk/hie-cm/profile/search/search.md). 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`. 

**3. Send the OTP**

Send `method`, `identifier` and `otp_system` to [Generate OTP](https://developer.eka.care/api-sdk/hie-cm/login/init.md):

* 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.

**4. Verify the OTP**

Send `txn_id` and `otp` to [Verify OTP](https://developer.eka.care/api-sdk/hie-cm/login/verify.md). 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. 

**5. Complete the mobile login**

Send `txn_id` and the chosen address as `phr_address` to [Login](https://developer.eka.care/api-sdk/hie-cm/login/login.md). The response carries `skip_state` set to `abha_end`, `profile` and `eka.oid`.

**6. Complete the Aadhaar login**

Send `txn_id` and the chosen `abha_address` to [Auto Login](https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/auto-login.md). 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](https://developer.eka.care/docs/hie-cm/workflows/hold-gateway-session.md) 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

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](https://developer.eka.care/docs/hie-cm/errors.md), 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](https://developer.eka.care/docs/hie-cm/errors.md). 

| 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](https://developer.eka.care/docs/hie-cm/testing.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.