abdm-m1-abha

name	abdm-m1-abha
description	Integrate ABDM Milestone 1 - ABHA creation (Aadhaar OTP, mobile OTP, face auth), ABHA login, profile management, KYC, ABHA card/QR generation, and the M1 web SDK. Use when the user says "integrate M1", "create ABHA", "ABHA login", "Aadhaar OTP flow", "ABHA card", or is building patient registration for an HIS/LMIS/PHR.

M1 — ABHA Identity Integration

Prereq: working auth (see abdm-auth skill). All M1 flows require an access token from the Session/Login API; the oid (Eka User ID) obtained is reused across all downstream flows.

Decision 1 — integration method (three options)

• Web SDK (fastest, prebuilt themed UI): CDN-loaded @eka-care/abha, mounted via window.initAbhaApp(...). Exact mount contract, method/flow enums, theme shape, and native-bridge hooks: references/web-sdk.md. Also fetch /SDKs/web-sdk/abha-sdk/get-started.md for current docs.
• Hosted web flows (zero frontend code): redirect/QR to Eka-hosted URLs for registration, KYC, consent, Scan & Share — URL table in references/web-sdk.md.
• Raw REST APIs: full control, needed for native mobile apps or custom UX. Flows below.

Ask the user which fits their HIS frontend. For branding (colours/logo/theme), check for a client config file first (abdm-auth/references/client-config.md) before asking piecemeal branding questions — also confirm embed point and language.

Decision 2 — which creation/login methods to enable?

Create ABHA

1. Aadhaar OTP (produces KYC-verified ABHA Number): initiate-registration → verify-otp → (if mobile not Aadhaar-linked: mobile-verify + resend) → create-abha. Docs under enrollment/aadhaar/.
2. Mobile OTP (ABHA address only, not KYC): enrollment/mobile/{init,verify,resend,create}.md.
3. Face auth (assisted, no OTP): enrollment/face-auth/* — init → capture (async, poll) → verify → create.

Login

1. Via PHR address: OTP init → verify → skip_state = abha_end (done).
2. Via Aadhaar: OTP → verify → skip_state = abha_create → Auto-Login API → abha_end.
3. Via mobile: OTP → verify → PHR Login API → abha_end.

Key state machine fact: on verify, inspect skip_state. If abha_create and len(abha_profiles) > 0, call Auto-Login to enter an existing ABHA rather than creating a duplicate.

Supporting APIs

• Profile: get/update/delete (profile/details/*), KYC upgrade (profile/kyc/*), ABHA card + QR (profile/cards/*), search (profile/search/search.md).
• Commons: does-health-id-exist, suggest-abha-address, pincode-details.
• Webhook: abha.abha_created fires on successful creation — wire it to create/update the patient record in the client's HIS.

Integration blueprint (what to build in the client codebase)

1. Backend module abha/: token-authed proxy endpoints for each enabled flow (never expose Eka creds to the browser), txn-state handling (txn_id passthrough), webhook receiver for abha_created.
2. HIS mapping: on ABHA created/logged-in, upsert {abha_address, abha_number, oid} onto the client's patient entity. Ask the user which table/model stores patients and add the columns/migration.
3. UI: registration screen(s) with method selector, OTP input with resend + 30-min lockout messaging (ABDM-1100), and error states from the errors table.
4. Compliance guards: Aadhaar number only in-memory, never logged; mobile stored only as last-4; OTPs never persisted.

Before writing any endpoint call, fetch its .md doc page for the exact schema (paths in ../abdm-overview/references/docs-map.md).

Test before done (see abdm-testing skill)

Sandbox happy paths: Aadhaar create, mobile create, each enabled login, duplicate-ABHA path (auto-login), wrong OTP (MIS-1013), OTP rate-limit (ABDM-1100).