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

# Set up the patient's health locker

> Turn on auto-approval so the patient's PHR app is notified of each new record, and handle the locker and subscription webhooks.

## In short

* Turn on auto-approval once, and your app becomes the patient's health locker.
* Store `auto_approval_id` and `subscription_id` from `abha.locker_created`.
* `abha.subscription_notify` tells you each time a HIP links a new care context.
* The notification carries no records; fetch them with a consent request.

## When to use this

Your app is a personal health record (PHR) app, and the patient wants new records from their facilities to arrive without approving each one. An auto-approval policy lets the patient authorise a class of requests once. With it in place, your app is the patient's health locker. Eka sets up an auto-approval and a subscription. It tells you each time a Health Information Provider (HIP) links a new care context to the patient's ABHA address.

For one request at a time, the patient approves or denies by hand: [Approve, deny or revoke a consent in a PHR app](https://developer.eka.care/docs/hie-cm/workflows/phr-act-on-consent.md).

## Before you start

* A bearer token for the API. See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md).
* A live ABHA Gateway session for the patient. Every consent operation needs one. See [User Session](https://developer.eka.care/docs/hie-cm/session/getting-started.md).
* The patient's Eka user id (`oid`).
* A webhook endpoint registered with Eka that verifies the `Eka-Webhook-Signature` header. See [Webhook signature](https://developer.eka.care/docs/webhooks/webhook-signature.md).
* Your keyset registered, if you manage the data on your side, so records fetched for the locker can be encrypted for you. See [Request a patient's consent as a HIU](https://developer.eka.care/docs/hie-cm/workflows/hiu-request-consent.md).

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your PHR app
  participant Eka
  participant HIP
  App->>Eka: GET /abdm/v1/consents/auto-approval
  App->>Eka: PATCH /abdm/v1/consents/auto-approval
  Eka-->>App: webhook abha.locker_created
  HIP->>Eka: new care context linked
  Eka-->>App: webhook abha.subscription_notify
  Eka-->>App: webhook abha.subscription_modified
```

## Steps

**1. Check the current policy**

Call [Get Status](https://developer.eka.care/api-sdk/hie-cm/consents/auto-approval/get-status.md) with the patient's `oid`. The response carries `status`, either `enabled` or `disabled`. If it is `enabled`, the locker is already set up; skip to handling the webhooks.

**2. Turn on auto-approval**

Call [Update Auto Approval Policy](https://developer.eka.care/api-sdk/hie-cm/consents/auto-approval/update-auto-approval-policy.md). The body is `application/x-www-form-urlencoded` and carries the patient's `oid`. The response carries the new `status`.

**3. Store the locker ids**

Wait for [`abha.locker_created`](https://developer.eka.care/docs/hie-cm/webhooks/locker-created). Reply `200` within 5 seconds; Eka retries on any other status. Store `data.auto_approval_id` and `data.subscription_id` against the patient (`data.oid`, `data.abha_address`). Together they identify the standing arrangement.

**4. Handle new care contexts**

Each time a HIP links a new care context to the patient's ABHA address, Eka sends [`abha.subscription_notify`](https://developer.eka.care/docs/hie-cm/webhooks/subscription-notify). Reply `200` within 5 seconds. Read `data.subscription_meta`: `hip_id` (the HIP that created the record), `event_id`, and `care_contexts`, each with `care_context_id` and `patient_reference`.

The notification carries no records. To fetch them:

1. Raise a consent request for those care contexts with [Request a patient's consent as a HIU](https://developer.eka.care/docs/hie-cm/workflows/hiu-request-consent.md).
2. Receive them with [Receive and decrypt records as a HIU](https://developer.eka.care/docs/hie-cm/workflows/hiu-receive-data.md).

**5. Handle subscription changes**

When the subscription changes, Eka sends [`abha.subscription_modified`](https://developer.eka.care/docs/hie-cm/webhooks/subscription-modify). Reply `200` within 5 seconds. Read `data.subscription_details`: `subscription_id`, `period` (`from`, `to`), `categories` (such as `DATA` and `LINK`) and `status` (such as `GRANTED`). Update your stored subscription to match.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `auto_approval_id` | `abha.locker_created` | As long as the locker is active | Identifying the auto-approval behind the locker |
| `subscription_id` | `abha.locker_created` | As long as the subscription is active | Matching `abha.subscription_modified` to the patient |
| Subscription `status`, `period`, `categories` | `abha.subscription_modified` | Until the next update | Whether new care contexts will be notified |
| `care_context_id`, `hip_id` | `abha.subscription_notify` | Until you have fetched the records | Raising the consent request for the new records |
| `event_id` | `abha.subscription_notify` | | Deduplicating retried deliveries |

## 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` (`code`, `message`). Codes are listed on the [errors page](https://developer.eka.care/docs/hie-cm/errors.md).

| Situation | Code | Do |
| - | - | - |
| ABHA Gateway session expired | HTTP `491` | Re-run the session OTP, then retry. See [User Session](https://developer.eka.care/docs/hie-cm/session/getting-started.md) |
| `oid` missing or not recognised | `ABDM-1023`, `ABDM-1110` | Check you sent the patient's Eka user id |
| Subscription request id not recognised | `ABDM-1054` | Not documented yet |
| Your endpoint does not reply `200` within 5 seconds | none | Eka retries; reply first, process after |
| Gateway unavailable | `ABDM-1024`, `ABDM-1048` | 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.

Sandbox base URL: `https://api.dev.eka.care`. 

* [ ] Get Status returns `disabled` for a new sandbox patient
* [ ] Update Auto Approval Policy returns `enabled`; `abha.locker_created` arrives with `auto_approval_id` and `subscription_id`
* [ ] Get Status now returns `enabled`
* [ ] Link a new care context at a sandbox HIP; `abha.subscription_notify` arrives with its `care_context_id`
* [ ] Raise a consent for that care context and confirm whether it is approved without a prompt
* [ ] Let the session expire and confirm the `491` path


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