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

# Approve, deny or revoke a consent in a PHR app

> Show the patient their pending consent requests, record their decision with their consent PIN, and revoke access later.

## In short

* Show the patient each pending request, then approve or deny it after their consent PIN.
* Approval creates one consent artefact per HIP.
* The patient can later revoke any artefact on its own.
* Whether `abha.consent_update` reaches a PHR app is not confirmed; fall back to List Requests.

## When to use this

Your app is a personal health record (PHR) app. A Health Information User (HIU) such as a doctor, hospital, insurer or another PHR app has asked for the patient's records. This workflow shows the patient the request, records their decision, and lets them revoke a granted consent later. On approval, ABDM generates one consent artefact per Health Information Provider (HIP), and the patient can revoke each artefact on its own.

To stop asking the patient for every request from a trusted source, set up auto-approval instead: [Set up the patient's health locker](https://developer.eka.care/docs/hie-cm/workflows/set-up-health-locker.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`), sent as the `X-Pt-Id` header. 
* 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).

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your PHR app
  participant Eka
  participant GW as ABDM gateway
  App->>Eka: GET /abdm/v1/requests
  App->>Eka: GET /abdm/v1/request
  App->>Eka: GET /abdm/v1/consents/pin/exists
  App->>Eka: POST /abdm/v1/consents/pin/set
  App->>Eka: POST /abdm/v1/consents/pin/verify
  alt Patient approves
    App->>Eka: POST /abdm/v1/consents/approve
    Eka->>GW: consent artefacts, one per HIP
  else Patient denies
    App->>Eka: POST /abdm/v1/consents/deny
  end
  Eka-->>App: webhook abha.consent_update (not yet confirmed)
  App->>Eka: POST /abdm/v1/consents/revoke
  Eka-->>App: webhook abha.consent_update (not yet confirmed)
```

## Steps

**1. List the patient's pending requests**

Call [List Requests](https://developer.eka.care/api-sdk/hie-cm/patient-requests/list-requests.md) with `type` set to `consent` and `status` set to `requested`. Both parameters are required.

Show the patient who is asking (`hiu`, `requester`) and why (`purpose`). Keep the `id` of the request they open. To show granted consents they can revoke, call again with `status` set to `granted`.

**2. Show the request's details**

Call [Requests Get Details](https://developer.eka.care/api-sdk/hie-cm/patient-requests/requests-get-details.md) with `id` and `type` set to `consent`. The response carries `hi_types` (the record types asked for), `duration` (`from`, `to`), `erase_at`, `access_mode` and `providers`. Each provider names a `hip` (`id`, `name`), its `care_contexts` (`id`, `display`) and, once granted, its `consent_artefact_id`.

Let the patient choose which providers, care contexts and record types to share.

**3. Check whether the patient has a consent PIN**

Call [Consent pin exists](https://developer.eka.care/api-sdk/hie-cm/consents/pin/exists.md). If `exist` is `true`, go to the verify step. If `false`, set one first.

**4. Set a consent PIN (first time only)**

Ask the patient to choose a PIN and send it as `pin` to [Consent pin set](https://developer.eka.care/api-sdk/hie-cm/consents/pin/set.md). Eka returns `204`.

**5. Verify the consent PIN**

Ask the patient for their PIN and send it as `pin` to [Consent pin verify](https://developer.eka.care/api-sdk/hie-cm/consents/pin/verify.md) before you approve or revoke. Eka returns `204`.

**6. Approve or deny**

**To approve,** call [Consent Approve](https://developer.eka.care/api-sdk/hie-cm/consents/consent-approve.md). Send `id` (the request id) and `consent_artefacts`, both required. Add one `consent_artefacts` item per HIP the patient chose, with `hip_id`, the chosen `care_contexts` (`id`, `display`), `hi_types`, `access_mode` (`view`), `duration` and `erase_at`. Eka returns `204`.

**To deny,** call [Consent Deny](https://developer.eka.care/api-sdk/hie-cm/consents/consent-deny.md) with `id` and, optionally, the patient's `reason` in plain text. Eka returns `204`.

Then update the request in your inbox. Whether a PHR app receives [`abha.consent_update`](https://developer.eka.care/docs/hie-cm/webhooks/consent-update) for requests the patient acts on is not yet confirmed. If it arrives, reply `200` within 5 seconds and read `data.notification.status`. If it does not, call [List Requests](https://developer.eka.care/api-sdk/hie-cm/patient-requests/list-requests.md) with `type` set to `consent` and `status` set to `granted`, or `denied` after a denial. Find the request by `id`.

**7. Revoke a granted consent (later)**

When the patient wants to cut off a HIP, call [Requests Get Details](https://developer.eka.care/api-sdk/hie-cm/patient-requests/requests-get-details.md) for the granted request and read `providers[].consent_artefact_id`. Verify the PIN again, then send the artefact ids to cut off as `consent_artefacts` to [Consent Revoke](https://developer.eka.care/api-sdk/hie-cm/consents/consent-revoke.md). Eka returns `204`. Artefacts you leave out stay granted.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| Request `id` | List Requests | Until the patient acts, then as long as you show the request in history | Get Details, Approve, Deny |
| `consent_artefact_id` per HIP | Get Details, after grant | Until the artefact is revoked or expires | Revoke |
| Request `status` | `abha.consent_update`, or List Requests | Until it changes | Showing the inbox correctly |
| Whether a PIN is set | Consent pin exists | | Choosing set or verify |

The patient's PIN is not state. Do not store it.

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

| 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) |
| Wrong PIN | Not documented yet | Let the patient retry |
| Patient forgot the PIN | none | Use [Consent pin forgot init](https://developer.eka.care/api-sdk/hie-cm/consents/pin/forgot-init.md), [Consent pin forgot verify](https://developer.eka.care/api-sdk/hie-cm/consents/pin/forgot-verify.md) and [Consent pin reset](https://developer.eka.care/api-sdk/hie-cm/consents/pin/reset.md) |
| Patient wants to change the PIN | none | Send `old` and `new` to [Consent pin change](https://developer.eka.care/api-sdk/hie-cm/consents/pin/change.md) |
| Missing `id` or `consent_artefacts` | `ABDM-1006`, `ABDM-1010` | Fix the body and resend |
| Request expired before the patient acted | `ABDM-1061` | Tell the patient; the HIU must raise a new request |
| Consent request id not recognised | `ABDM-1039` | Refresh the inbox from List Requests |
| 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.

* [ ] Raise a request against a sandbox patient with [Request a patient's consent as a HIU](https://developer.eka.care/docs/hie-cm/workflows/hiu-request-consent.md)
* [ ] It appears in List Requests with `status` `requested`; Get Details shows its providers and care contexts
* [ ] Pin exists returns `false` for a new patient; set a PIN; exists now returns `true`
* [ ] Verify the PIN and approve one care context. Record whether `abha.consent_update` arrives (not yet confirmed); otherwise List Requests with `status` `granted` shows the request
* [ ] Get Details now shows a `consent_artefact_id`; revoke it
* [ ] Deny a second request with a reason
* [ ] Let the session expire and confirm the `491` path


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