abdm-m3-consent

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

1. consent-create.md — specify patient ABHA address, purpose code, hi_types, date range, expiry.
2. Patient approves on their PHR app. Eka handles all gateway callbacks.
3. 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.
4. 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

1. Webhook receiver handles abha.consent_update and abha.hiu_data_push (idempotent — data can arrive in multiple parts).
2. 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.
3. Decryption + FHIR parsing pipeline into the client's data model (abdm-fhir skill).
4. 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.