Technical Reference

Architecture & Security

UHIN’s five-layer federated architecture, FHIR R4 data model, 11 ABDM API contracts, zero-trust security framework, and full regulatory compliance — all in one reference.

FHIR R4 HAPI FHIR ABDM HIP/HIU AES-256 Zero-trust IAM DPDP Act 2023 CERT-In
Four-Layer System

Decoupled architecture — each layer independently deployable

Each layer communicates with the adjacent layer only through well-defined, authenticated APIs. The data vault (Layer 4) is physically and logically isolated from the portal (Layer 2). Zero clinical data in the portal layer.

Layer 1
ABDM Compliance Spine
ABHA Registry · HIP/HIU Gateway · PHR Consent App · FHIR R4/HL7 Data Exchange
NRCeS India profiles · NHA sandbox certification · ABDM Facility Registry · CoWIN vaccination bridge
Layer 2
Unified Portal
Next.js 14 App Router · React Native · WhatsApp Bot (rural access) · REST/FHIR APIs for EMR integration
Role-based module router · i18n Hindi + 10 regional languages · PWA offline support · Zero clinical data stored here
Layer 3
Interoperability Bus
Apache Kafka (AWS MSK) · Kong API Gateway · Consent Engine · mTLS Service Mesh
FHIR REST APIs · Event streaming · WORM audit trail · Rate limiting · Circuit breakers · gRPC internal services
Layer 4
Secure Health Data Vault
HAPI FHIR R4 · AWS RDS PostgreSQL 15 (Multi-AZ) · AWS KMS (per-patient keys) · AES-256
5 purpose-separated stores · PII tokenisation at ingest · WORM audit log · India data residency (NIC MeghRaj / AWS ap-south-1) · ETL → S3 → Athena analytics
ABDM Integration

8-step consent and data-exchange flow

1

ABHA Creation

Patient registers once. ABDM issues 14-digit ABHA number + ABHA address (user@abdm). UHIN links patient profile to this ABHA ID across all facilities.

2

HIP Onboarding

Hospital registers with UHIN and simultaneously as ABDM HIP. NHA issues Client ID + Secret — stored in AWS Secrets Manager, never in source code.

3

Care Context Creation

Every encounter (OPD, lab, prescription) creates a FHIR Bundle + registers a care context with ABDM gateway. Care context = pointer to a health record event.

4

Discovery Request

Doctor initiates ABHA lookup. ABDM gateway sends discovery request to all registered HIPs. UHIN responds with matching care contexts for that ABHA ID.

5

Consent Notification

ABDM consent manager pushes OTP notification to patient's ABHA Health app. Patient sees: who is requesting, what records, purpose, and duration.

6

Patient Grants Consent

Patient approves via OTP. ABDM issues a digitally signed, time-bound consent artefact — specifying requester, purpose, HI types, and date range.

7

FHIR Bundle Transfer

UHIN (HIP role) validates the artefact, fetches matching FHIR bundles, encrypts with requester's public key, POSTs to HIU's dataPushUrl.

8

Display + WORM Audit

Receiving UHIN (HIU role) decrypts the bundle, renders records in consultation workspace, writes an immutable WORM audit log entry that can never be modified.

API Reference

11 API endpoints

Method Endpoint Description Type
FHIR R4 Data Model

13 India-specific resources

All resources conform to NRCeS Implementation Guide profiles — mandatory for ABDM HIP certification. India-specific extensions: CDSCO drug codes, NMC practitioner IDs, CoWIN vaccination, ICD-10 India variant.

🏥 Clinical Store
Encounter · Condition · Rx · DiagnosticReport · Immunization
💳 Claims Store
Coverage · Claim · ClaimResponse · ExplanationOfBenefit
💊 Pharmacy Store
MedicationDispense · SupplyDelivery · MedicationKnowledge
📊 Analytics Store
De-identified · Group · Measure · k-Anonymised · IRB-gated
🗂️ Master Data
Organization · Practitioner · Location · Device
FHIR ResourceStoreIndia-specific notes
Technology Stack

Production-grade. India-first.

⚕️
ABDM / FHIR
HAPI FHIR R4 · NHA ABDM Gateway APIs · NRCeS India profiles · HL7 FHIR R4 · ABHA Health ID APIs · CoWIN bridge
🖥️
Portal Frontend
Next.js 14 App Router · TypeScript · Tailwind CSS · shadcn/ui · React Query · React Native · PWA offline
🔀
API & Events
Kong API Gateway · Apache Kafka (AWS MSK) · Node.js microservices · gRPC internal · mTLS service mesh
🗄️
Data Vault
HAPI FHIR Java · AWS RDS PostgreSQL 15 Multi-AZ · AWS KMS per-patient keys · Glue ETL · S3 · Athena
🔒
Security
AWS WAF + Shield · CloudTrail · Secrets Manager · ACM Private CA · Zero-trust IAM · AES-256 · CERT-In
☁️
Infrastructure
AWS Mumbai ap-south-1 · EC2 Auto Scaling · RDS Multi-AZ · CloudWatch · VPC private subnets · ALB
Encryption Architecture

Per-patient encryption keys

Every patient's records are encrypted with their own unique AWS KMS customer-managed key. A breach of one patient's key is entirely contained — it cannot affect any other patient's data. Key deletion means permanent, auditable erasure.

AES-256 field-level encryption

Name, DOB, mobile, and Aadhaar reference encrypted at field level using AES-256-GCM with a unique per-patient AWS KMS key. Annual automated rotation.

TLS 1.3 everywhere

External HTTPS uses TLS 1.3 minimum. Internal service-to-service uses mTLS 1.3 via AWS ACM Private CA certificates. Cipher suite: CHACHA20_POLY1305 and AES_256_GCM only.

PII tokenisation at ingest

All PII replaced with ABHA-linked tokens before data crosses into analytics or claims stores. The tokenisation map lives in the clinical store only — analytics layers never see patient identity.

Right to erasure via KMS deletion

Patient requests deletion → UHIN deletes their AWS KMS key → all encrypted records permanently inaccessible within 72 hours. Compliant with DPDP Act Section 12.

KMS Architecture — Code
// Per-patient encryption — simplified Patient: "Ravi Kumar" abha_id: "43-2187-3456-1892" kms_key_id: "arn:aws:kms:ap-south-1 :acct:key/ravi-uuid" // PII fields — AES-256-GCM encrypted name_enc: <ciphertext> dob_enc: <ciphertext> mobile: "XXXXXXX4512" // masked // Analytics Store — ZERO PII ever AnalyticsRecord: abha_token: "tok_7f3a2b..." // "Ravi Kumar" → opaque token only condition: "E11.9" district_lgd: "563" age_band: "40-49" // Erasure — DPDP Act Section 12 aws kms schedule-key-deletion \ --key-id ravi-uuid \ --pending-window-in-days 7 // ✓ All records: permanently // inaccessible after 7 days.
AWS KMS ap-south-1 Annual key rotation DPDP Act S.12
Identity & Access

Zero-trust IAM — never trust, always verify

Every API call — internal or external — requires a valid JWT + active ABDM consent artefact for clinical data. No implicit trust. No persistent sessions. No direct internet access to the data vault.

5-layer defence in depth

1
AWS WAF + Shield
DDoS mitigation, rate limiting, geo-blocking for sensitive endpoints
2
Kong API Gateway
JWT validation, RBAC enforcement, rate limiting per client, mTLS
3
Consent Engine
Every FHIR data request validated against ABDM consent artefact — live, never cached
4
ABAC at data layer
Attribute-based policies enforce facility_id + consent_scope per DB query
5
WORM Audit Log
DB trigger blocks UPDATE/DELETE — every access permanently recorded

Access control matrix

RoleClinicalAnalyticsPII
treating_doctorConsented ptsMasked
hospital_adminOwn facility
insurance_analystClaims only
pharma_researcherDe-identified
patient (self)Own recordsOwn only

JWT 15-minute expiry — access tokens. Redis blocklist for instant revocation.

MFA mandatory — TOTP + biometric for clinical and insurance roles. Cannot be disabled.

Zero secrets in code — all credentials via AWS Secrets Manager, rotated every 90 days.

Regulatory Compliance

Every relevant framework. Covered.

🏥
ABDM / NHA Guidelines

All 11 mandatory ABDM HIP/HIU APIs implemented. NRCeS FHIR profiles loaded. 48 sandbox test cases passing. HIP certification filed Month 2. Dual HIP + HIU role operation.

Full — Phase 1HIP + HIUNRCeS profiles
📜
DPDP Act 2023

Data fiduciary duties, purpose limitation, consent artefacts, right to erasure via KMS key deletion (S.12), grievance officer per S.13, privacy notice in portal.

Full — Phase 1S.12 ErasureS.13 Grievance
💻
IT Act 2000 / SPDI Rules 2011

Reasonable security practices (AES-256 + TLS 1.3). India data localisation — all data on AWS Mumbai or NIC MeghRaj. CERT-In registered entity. 72-hour breach notification SLA in runbook.

Full — Phase 1CERT-InIndia residency
🛡️
IRDAI Health Data Regulations

Insurance health data physically isolated in the Claims Store, separate from the Clinical Store. Pre-auth API compliant with IRDAI Cashless Claims Committee spec. 7-year data retention.

Phase 2Claims store isolated
Threat Model

How UHIN defeats the top six threats

🕵️

Unauthorised data access

Zero data access without valid ABDM consent artefact validated live. ABAC policies enforce facility and department boundaries at the database layer.

💻

Portal layer breach

Portal stores zero clinical data. A complete portal compromise exposes only UI code. Clinical records are in the air-gapped data vault — inaccessible without consent + KMS key.

🔑

Credential theft

JWT 15-minute expiry + Redis revocation. MFA mandatory. No persistent sessions. All service credentials in AWS Secrets Manager — zero hardcoded keys.

📦

Supply chain attack

Container images scanned via AWS ECR. Dependency audit on every CI/CD build. Internal services use mTLS certificates only — no third-party SDK with network access in the vault.

💥

DDoS / availability

AWS Shield Advanced on all external endpoints. WAF rules block malformed FHIR requests. Kafka queue decouples ingest from processing — ABDM callbacks never dropped under load.

🗑️

Data destruction

RDS automated backups with 7-day retention and cross-AZ replication. S3 Versioning + Object Lock for WORM compliance. KMS key deletion has mandatory 7-day pending window.

"UHIN is built on one principle: clinical data must be technically inaccessible without patient consent — not just policy-restricted. The system cannot access your records without your active permission. This is zero-knowledge architecture applied to health data."

Need a full security audit report?

We provide detailed security documentation for enterprise procurement, ABDM partner onboarding, and investor due diligence.