| name | abdm-m3-consent |
| description | Integrate ABDM Milestone 3 - consent lifecycle (create, list, approve, deny, revoke), auto-approval policies, HIU data fetching, hiu_data_push webhook, and decryption keysets. Use when the user says "integrate M3", "consent request", "HIU", "fetch patient records", "consent artefact", or is building an insurer/referral/analytics/PHR consent feature. |
M3 — Consent Management & Data Fetching
Two sides; a client may need one or both. Ask which:
- HIU side (insurer, referral, analytics, doctor pulling outside history): create consent requests, receive data.
- PHR/patient side: list incoming requests, approve/deny/revoke, auto-approval.
All consent operations require user authorization (the patient's session), not just client auth.
Integration method
A Consent Management SDK exists (consent-management/get-started.md in the docs map) as an alternative to raw APIs — mention it alongside raw APIs the same way M1 offers a Web SDK. Ask which the client wants; don't assume raw API by default.
HIU flow
consent-create.md — specify patient ABHA address, purpose code, hi_types, date range, expiry.- Patient approves on their PHR app. Eka handles all gateway callbacks.
- Receive data — default to client manages data: register an HIU public keyset first (
care-contexts/hiu-keys.md); then abha.hiu_data_push webhook delivers encrypted FHIR + key_information → decrypt (ECDH, see ../abdm-m2-care-context/references/ecdh-encryption.md) → parse with abdm-fhir skill. Letting Eka store/serve the data instead (consent-details.md after approval → care_context_ids → Retrieve Health Records API) is not an enabled option for most accounts today — same as M2's data custody — only offer it if the client already knows it's enabled on their account.
- Track consent state via
consent-list/consent-details and the consent-update webhook.
PHR flow
consent-list → render pending requests → consent-approve (choose care contexts + HIPs; generates one artefact per HIP) / consent-deny (with reason) / consent-revoke (per artefact). Auto-approval policies: auto-approval/update-auto-approval-policy.md.
Consent state machine (persist this)
requested → granted (artefacts issued) | denied; granted → revoked | expired. Store: consents(consent_id, patient_abha, purpose, hi_types, date_from, date_to, status, granted_at, expires_at). Never fetch data on an expired/revoked artefact (ABDM-1061/1062 errors).
Integration blueprint
- Webhook receiver handles
abha.consent_update and abha.hiu_data_push (idempotent — data can arrive in multiple parts).
- UI: consent request composer (HIU) or consent inbox (PHR). Purpose codes and hi_types must be user-selectable but constrained to what the client is certified for.
- Decryption + FHIR parsing pipeline into the client's data model (
abdm-fhir skill).
- Expiry job: mark expired consents, purge fetched data per retention policy.
Fetch each endpoint's .md before coding (paths: ../abdm-overview/references/docs-map.md).
Test before done
Create→approve→data received (both custody modes as applicable), deny path, revoke after grant, expired-consent fetch rejection, multi-HIP consent producing multiple artefacts.
