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

# Hold the ABHA Gateway session

> Check whether the patient's ABHA Gateway session is live and renew it with a mobile OTP when it has expired.

## In short

* Patient-scoped calls without a live ABHA Gateway session return HTTP `491`.
* Check the session with Status, and renew it with Init and Verify on a mobile OTP.
* Once the session is live, retry the call that returned `491`.

## When to use this

Registering or creating an ABHA opens a session for the patient with the ABHA Gateway. Whether logging in also opens one is not yet confirmed.  The session expires after a period. Patient-scoped calls made without a live session return HTTP `491`. Run this workflow before a patient-scoped call such as fetching the profile, and whenever a call returns `491`.

This workflow renews a session for a patient whose ABHA you already hold. To find or create the ABHA in the first place, use [Log in to an existing ABHA](https://developer.eka.care/docs/hie-cm/workflows/login-abha.md) or one of the create workflows.

## 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).
* The patient's `oid` and `abha_address`, stored when the ABHA was created or the patient logged in. Session Status needs the `oid` in the `X-Pt-Id` header.
* Access to the patient's phone for the mobile OTP.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient's phone
  App->>Eka: GET /abdm/v1/session/status
  alt logged_in is true
    Note over App,Eka: Session is live, continue with your call
  else logged_in is false, or a call returned 491
    App->>Eka: POST /abdm/v1/session/init
    Eka-->>Patient: Mobile OTP
    App->>Eka: POST /abdm/v1/session/verify
  end
```

## Steps

**1. Check the session**

Call [Status](https://developer.eka.care/api-sdk/hie-cm/session/status.md) with the patient's `oid` in the `X-Pt-Id` header. The response carries `logged_in`, `kyc_verified` and `hpr_id`.

* `logged_in` is `true`: the session is live. Continue with the patient-scoped call you were about to make.
* `logged_in` is `false`: renew the session with the next two steps.

**2. Send the mobile OTP**

Send the patient's `abha_address` to [Init](https://developer.eka.care/api-sdk/hie-cm/session/init.md), with the `oid` in the `X-Pt-Id` header or the `oid` query parameter. An OTP goes to the patient's mobile. The response carries `txn_id`. 

**3. Verify the OTP**

Send `txn_id` and `otp` to [Verify](https://developer.eka.care/api-sdk/hie-cm/session/verify.md), with the same `oid`. The response carries `token`, the user's access token, and `refresh_token`. The session is live again. Retry the call that returned `491`.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `oid` | The create or login workflow | Permanently, on the patient record | `X-Pt-Id` header on every call here |
| `abha_address` | The create or login workflow | Permanently, on the patient record | Session Init |
| `txn_id` | Session Init | Until Session Verify returns | Session Verify |
| `token` | Session Verify | Until the session expires | Not documented |
| `refresh_token` | Session Verify | 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 |
| - | - | - |
| Session expired on a patient-scoped call | HTTP `491` | Run Session Init and Session Verify, then retry the call. |
| Session Status called without `X-Pt-Id` | Not documented | Send the patient's `oid` in `X-Pt-Id`. |
| 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. |
| No ABHA found for the address | `ABDM-1012`, `ABDM-1110` | Check the stored `abha_address` against the patient record. |
| Expired or unknown transaction | `ABDM-1017`, `MIS-1026` | Start again from Session Init. |
| 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.

Run against the sandbox base URL `https://api.dev.eka.care`, with an ABHA you created on sandbox. 

* [ ] Straight after creating an ABHA, Session Status returns `logged_in: true`.
* [ ] After the session expires, Session Status returns `logged_in: false`. Session Init and Session Verify return a `token`; Session Status returns `logged_in: true` again.
* [ ] A patient-scoped call such as [Profile Details](https://developer.eka.care/api-sdk/hie-cm/profile/details/profile-details.md) returns `491` on an expired session and succeeds after renewal.
* [ ] Wrong OTP on Session Verify: `MIS-1013`. Record the code you receive; the expected code is not confirmed.


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