Authentication

All ABDM services use client-credential sessions: exchange your clientId + clientSecret for a short-lived JWT bearer token, then send it as Authorization: Bearer <token> on every call.

Getting a session token

curl -X POST "https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions" \
-H "Content-Type: application/json" \
-H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
-H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
-H "X-CM-ID: sbx" \
-d '{
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "grantType": "client_credentials"
}'

curl -X POST "https://dev.abdm.gov.in/api/hiecm/gateway/v3/sessions" \
  -H "Content-Type: application/json" \
  -H "REQUEST-ID: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "TIMESTAMP: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-CM-ID: sbx" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET",
    "grantType": "client_credentials"
  }'

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "expiresIn": 1200,
  "refreshExpiresIn": 1800,
  "refreshToken": "eyJhbGciOiJIUzUxMiIs...",
  "tokenType": "bearer"
}

Invalid credentials return 400 with an ABDM error envelope:

{
  "error": {
    "code": "ABDM-9999",
    "message": "Invalid user credentials"
  }
}

Required headers

Request body

Using the token

Authorization: Bearer <accessToken>
REQUEST-ID: 4c3197c0-1e3a-4a92-a319-a25d17e6f0c2
TIMESTAMP: 2024-07-09T11:25:00.000Z
X-CM-ID: sbx

Token management

• Cache and reuse tokens until near expiry (expiresIn is seconds); don't create a session per request.
• Clock skew matters — v3 APIs reject stale TIMESTAMP values; sync with NTP.
• Callback authenticity — validate JWTs on inbound gateway callbacks against the gateway's published certificates instead of trusting the network.

HPR / HFR (NHPR) tokens

The Milestone 4 HealthCare Professional and Facility Registry APIs run on a separate host (https://apihspsbx.abdm.gov.in/v4/int in sandbox) and use the same client-credential pattern, but note that several registration flows also involve user-level tokens (e.g. an hprToken from Aadhaar/OTP authentication) in addition to your gateway session. See the M4 guide for the full sequence.

Aadhaar / OTP payload encryption

Separate from transport auth, sensitive values (Aadhaar number, OTPs, and some mobile numbers) sent to ABHA and HPR APIs must be RSA-encrypted with the service's public certificate before being placed in the request body — TLS alone is not sufficient. Fetch the certificate once, encrypt with RSA/ECB/OAEPWithSHA-1AndMGF1Padding, and Base64-encode the result.

→ Full walkthrough with Node.js / Python / Java examples: Data Encryption.