Skip to main content

ABHA verification, mobile OTP

Verify a login OTP and get a user token

Returns the user scoped token that profile calls need, sent afterwards as the X-token header. That token identifies one person, so it is not interchangeable with the gateway session token, which identifies your application.

Mandatory

Certification cases VRFY_ABHA_101, VRFY_ABHA_201, VRFY_ABHA_301, VRFY_ABHA_302, VRFY_ABHA_303, VRFY_ABHA_304, VRFY_ABHA_305, VRFY_ABHA_401, VRFY_ABHA_402, VRFY_ABHA_403, VRFY_ABHA_404, VRFY_ABHA_405, VRFY_ABHA_501

POST/v3/profile/login/verify

If the identifier the person used maps to more than one ABHA, this responds with the list instead of a token, and you continue with the user selection call.

Documented responses cover 400, 401, 404 and 422 as well as 200, so read the body rather than only the status.

Authorizations

Authorizationbearer tokenRequired

The accessToken from POST /api/hiecm/gateway/v3/sessions. Send it as Authorization: Bearer <ACCESS_TOKEN>.

Headers

REQUEST-IDstringRequired

Unique UUID v4 per request. Used for idempotency and distributed tracing. Generate a fresh UUID for every call.

TIMESTAMPstringRequired

ISO 8601 UTC timestamp of the request.

BENEFIT_NAMEstring

The benefit scheme an enrolment belongs to. Send healthid api on the enrol and search calls, and healthid on the login OTP and verify calls under Find ABHA. On the enrolment OTP request the header is present but explicitly disabled, so it is not sent there.

A login OTP request sent with healthid api rather than healthid was accepted on the sandbox on 2026-09-11, so the login calls may take either.

NHA's files spell this header four different ways and use scheme values beyond healthid. Which spelling each endpoint accepts is not confirmed against the sandbox. The Conventions page for this module lists all four.

T-tokenstring

The transaction token that carries state between the two halves of a login. Returned by the verify call and sent back on the account selection call. Like X-token, the value carries a Bearer prefix in every one of the recorded requests.

X-tokenstring

The user scoped token returned when a person logs in or verifies an OTP. Profile calls act on one account, so they need this in addition to the gateway token. Required on the calls that read or change a specific person's account.

Send the bare token. Unlike the Authorization header this one carries no Bearer prefix, and adding one is refused as ABDM-1094 with the message X-token expired. That message names the wrong thing: a token rejected one second after it was issued has not expired, it was malformed. Check the prefix before the lifetime.

Body

scopestring[]Required
authDataobjectRequired
authData.authMethodsstring[]Required
authData.otpobject
authData.otp.txnIdstringRequired
authData.otp.otpValuestringRequired
authData.passwordobject
authData.password.ABHANumberstringRequired
authData.password.passwordstringRequired
authData.faceobject
authData.face.txnIdstringRequired
authData.bioobject
authData.bio.txnIdstringRequired
authData.bio.fingerPrintAuthPidstringRequired

Responses

200

Whether the login verified, with the user token and its expiry.

400

The response.

Error codes for this module

401

The error returned, with its code and message.

Everything returns 401

403

Forbidden, the token is valid but not permitted for this operation

Error codes for this module

404

The error returned, with its code and message.

Error codes for this module

422

The error returned, with its code and message.

Error codes for this module

500

Server error, retry

Error codes for this module

Last updated on