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. Three things follow.

• You get an acknowledgement, not an answer. In the M3 consent flow the HIU asks, the HIE-CM acknowledges with a consent request id, 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. A HIP it cannot reach fails on someone else's logs, as ABDM-1028 HIP is unavailable.
• Order is enforced. The M2 error list carries ABDM-2406 Invalid API sequence flow, please follow logical flow.

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 same call in M1 and M4.

POST /api/hiecm/gateway/v3/sessions

Headers:

No Authorization header on this call. It is the one call with no token yet, and the collection marks it noauth.

Body, transcribed from the collection:

{
  "clientId": "healthid-api",
  "clientSecret": "<CLIENT_SECRET_FROM_SANDBOX_SIGNUP>",
  "grantType": "client_credentials"
}

The collection sends the literal healthid-api as the client id. The M4 document shows a per integrator value in the same field. Send whatever you were issued.

Response shape, from the M4 document, which prints it as text:

{
  "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​

Four hosts serve gateway paths.

Take the host from the sandbox documentation issued at onboarding, and keep it 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.