The ABDM gateway

The gateway is the routing layer for ABDM. You never call a hospital, a lab or a PHR app directly. The answer to a call arrives later at an endpoint you expose, and the gateway issues the access token every other call carries.

Gateway and HIE-CM are not the same thing​

HIE-CM is the service: patient identity, care context links and consent. Its four modules and who builds which are on Integration milestones.

The gateway is its front door. It authenticates you, validates your headers, and routes each call. Your consent request goes to /api/hiecm/consent/v3/request/init on the gateway host, and the gateway puts it in front of the patient's consent manager.

HIE-CM is data blind​

It never holds a patient's health record, only identifiers, metadata about where records live, and consent artefacts. Once consent exists the record goes straight from the system that holds it to the system that asked, encrypted. Your system keeps the data. HIE-CM keeps the permission.

Nothing goes participant to participant​

Every request is addressed to the gateway, which forwards it. Two things follow.

• You get an acknowledgement, not an answer. In the M3 consent flow the HIU asks, the HIE-CM returns the consent request id on a callback, and the patient's decision comes back later. Each call's page in the API reference names the callback it produces.
• You have to be reachable. Half of M2 is endpoints the gateway calls on your system.

One exception. In the health information flow the HIU supplies a data push URL, and the HIP encrypts the records and pushes them there. That URL may differ from the HIU's registered gateway URL, to improve privacy. The permission came through the gateway. The bytes do not.

What moves through it​

The gateway holds no health record. It routes the permission and the metadata.

The session endpoint​

One endpoint issues the token every other call carries. It is the call M1 uses. M4 declares bearer authentication, and its HPID calls publish POST /getManagementToken.

POST /api/hiecm/gateway/v3/sessions

Headers:

No Authorization header on this call. It is the one call with no token yet.

Body:

{
  "clientId": "<CLIENT_ID_FROM_SANDBOX_SIGNUP>",
  "clientSecret": "<CLIENT_SECRET_FROM_SANDBOX_SIGNUP>",
  "grantType": "client_credentials"
}

Send the client id you were issued.

Response shape:

{
  "accessToken": "<JWT>",
  "expiresIn": 1200,
  "refreshExpiresIn": 1800,
  "refreshToken": "<JWT>",
  "tokenType": "bearer"
}

The response carries the token in accessToken.

Send the token back as Authorization: Bearer <ACCESS_TOKEN_FROM_SESSIONS_CALL> on every other call. Headers per call, and the second token M1 login issues, are on authentication. Interactive: gateway API reference.

Which host​

Two hosts serve gateway paths.

Keep the host in configuration, not in code.

Limits to code against​

• Callback retries. Make your endpoint idempotent and assume a repeat.
• Gateway token lifetime. Read expiresIn from your own response rather than hard coding a value.
• Rate limits. Two codes enforce them: ABDM-1022 Too many requests and ABDM-1027 You are blocked. Please try again after 24 hours. The thresholds are not published, so back off on both.
• Request signing. The gateway request itself is not signed. Payload encryption and signing apply to health records, on the M2 side.

Next​

• Authentication, credentials and headers.
• API references, every call and the callback it produces.
• Integration milestones, the four modules and who builds which.
• Registries, who and what ABDM identifies.
• Error codes, what a rejection means.