ABDM Gateway

The central router for all consent and data-flow traffic between ecosystem participants.

The ABDM Gateway is the switchboard of the ecosystem. HIPs, HIUs, and consent managers never call each other directly for orchestration — everything routes through the gateway.

Responsibilities

Authentication — issues session tokens against client credentials.
Routing — forwards requests to the right CM / HIP / HIU based on ABHA-address suffix and registered bridges.
Callback delivery — delivers asynchronous results to your registered bridge callback URL.
Registry of bridges — knows which software serves which facility and which roles (HIP/HIU) it plays.

The gateway never sees health data in plaintext

Consent artefacts and routing metadata flow through the gateway, but actual FHIR bundles are encrypted end-to-end and pushed directly from HIP to the HIU's data-push URL.

The asynchronous pattern

Nearly every gateway API is a request/callback pair. You call the request endpoint, receive 202 Accepted immediately, and the result arrives later at your callback URL:

sequenceDiagram
  participant You as Your System
  participant GW as Gateway
  participant CM as HIE-CM
  You->>GW: POST /consent-requests/init (requestId: R1)
  GW-->>You: 202 Accepted
  GW->>CM: forward
  CM->>GW: result
  GW->>You: POST /on-init (requestId: R2, resp.requestId: R1)

Rules of the pattern:

Every request carries a unique requestId (UUID) and timestamp.
The callback references your original ID in resp.requestId — this is your correlation key.
Callbacks contain either a result or an error object — handle both.
Acknowledge callbacks fast (HTTP 200 with no heavy work inline); process asynchronously.
Timeouts are your responsibility — if no callback arrives, mark the operation failed and allow retry with a fresh requestId.

Headers you'll use constantly

Header	Purpose
`Authorization: Bearer <token>`	Gateway session token
`X-CM-ID`	Consent manager suffix (e.g. `sbx` in sandbox, `abdm` in production)
`X-HIP-ID` / `X-HIU-ID`	Identifies which of your bridge's facilities the callback targets

Bridge callback registration

Register (and update) your bridge's callback URL with the gateway. All on-* callbacks for your HIP/HIU IDs arrive at paths under this URL.

Conceptual: set bridge URL

curl -X PATCH "https://dev.abdm.gov.in/gateway/v1/bridges" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "url": "https://your-bridge.example.com/abdm" }'

Callbacks & Webhooks

Callback catalogue, correlation, and idempotency patterns.

Authentication

Sessions and token lifecycle.

PreviousHPR & HFR Registries Next HIP & HIU