---
title: "Response to user authentication initialization from HIP"
method: POST
path: "/v0.5/users/auth/on-init"
tags: ["user auth"]
---

# Response to user authentication initialization from HIP

`POST /v0.5/users/auth/on-init`

If the patient's id is valid, CM will return a transactionId as initialization of user auth. If the request is valid, then 'auth.mode' will convey how the authentication should be done. The authentication can be *mediated* or *direct*. For mediated authentication modes, HIP or HIU is epected to send over relevant code (OTP/token) or demographic info via subsequent API call to /auth/confirm. for direct authentication case, CM will notify requester through/users/auth/notify API. 

  1. **auth.mode** conveys whats the mode of authentication is, and what is expected from HIP/HIU in the subsequent /auth/confirm API call. Possible values 
      1. MOBILE_OTP - auth via OTP to registered mobile. Mediated. 
      2. AADHAAR_OTP - auth initiated with Aadhaar with OTP. Mediated. 
      3. DEMOGRAPHICS - auth initiated with demographic verification
      4. DIRECT - for authentication directly with the patient. e.g. Mobile App, SMS. In this case, the HIP/HIU is not expected to call subsequent /auth/confirm call. CM will do direct authentication with the User (e.g. Mobile App, SMS etc) and will notify requester
  2. **meta.expiry** conveys the expiry time of the token and the authentication session
  3. **NOTE**, only one of **X-HIP-ID** or **X-HIU-ID** will be sent as part of header, not both. 




















  
The error section in the body, represents the potential errors that may have occurred. Possible reasons:
  1. Patient id is invalid

## Headers

- `Authorization` string, required
- `X-HIP-ID` string, required
- `X-HIU-ID` string, required

## Request body

- PatientAuthInitResponse
  - `auth` object
    - `meta` AuthMeta
      - `expiry` string
      - `hint` string
    - `mode` 'MOBILE_OTP' | 'DIRECT' | 'DEMOGRAPHICS' | 'AADHAAR_OTP', required — Subjected to CM specific capability 1. MOBILE_OTP - for SMS OTP 2. DIRECT - for authentication directly with the patient. e.g. Mobile App, SMS 3. AADHAAR_OTP - for auth using OTP sent to Aadhaar number 4. DEMOGRAPHICS - for auth using demographic verification.
    - `transactionId` string, required
  - `error` Error
    - `code` 1000 | 10001, required
    - `message` string, required
  - `requestId` string, uuid, required — a nonce, unique for each HTTP request
  - `resp` RequestReference, required
    - `requestId` string, uuid, required — the requestId that was passed
  - `timestamp` string, date-time, required — Date time format in UTC, includes miliseconds YYYY-MM-DDThh:mm:ss.vZ

## Response `202`

Request accepted

## Other responses

- `400` — **Causes:** * required information not provided * neither authInit nor error specified
- `401` — **Causes:** * Unauthorized request
- `500` — **Causes:** * Downstream system(s) is down. * Unhandled exceptions.

---

[API](https://skmtc.net/ndhm/apis/ndhm-hip.md) · [All operations](https://skmtc.net/ndhm/apis/ndhm-hip/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ndhm/ndhm-hip/versions/26beb7157b70/schema)