---
title: "callback API for /auth/confirm (in case of MEDIATED auth) to confirm user authentication or not"
method: POST
path: "/v0.5/users/auth/on-confirm"
tags: ["user auth"]
---

# callback API for /auth/confirm (in case of MEDIATED auth) to confirm user authentication or not

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

This API is called by CM to confirm authentication of users.

  1. **auth.accessToken** - is specific to the purpose mentioned in the /auth/init. This token needs to be used for initiating the intended action. For example for HIP initiated linking of care-contexts
  2. **NOTE**, only one of **X-HIP-ID** or **X-HIU-ID** will be sent as part of header, not both.

## Headers

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

## Request body

- PatientAuthConfirmResponse
  - `auth` object — depending on the purpose of auth, as specified in /auth/init, the response may include the following 1. LINK - only returns **accessToken** 2. KYC - only returns **patient** 3. KYC_AND_LINK - returns both **accessToken** and **patient**
    - `accessToken` string — access token for initialization of subsequent action.
    - `patient` PatientDemographicResponse
      - `address` PatientAddress
        - `district` string
        - `line` string
        - `pincode` string
        - `state` string
      - `gender` 'M' | 'F' | 'O' | 'U', required
      - `id` string, required — PHR Identifier of patient at consent manager
      - `identifiers` Identifier[]
        - `type` 'MOBILE' | 'MR' | 'NDHM_HEALTH_NUMBER' | 'HEALTH_ID', required
        - `value` string, required
      - `name` string, required
      - `yearOfBirth` integer, required
    - `validity` AccessTokenValidity
      - `expiry` string, date-time, required — Date time format in UTC, includes miliseconds YYYY-MM-DDThh:mm:ss.vZ
      - `limit` integer, required — number of times, the token can be used
      - `purpose` 'LINK' | 'KYC' | 'KYC_AND_LINK', required — what is the purpose of user auth
      - `requester` PatientAuthRequester, required — identification of requester
        - `id` string, required
        - `type` 'HIP' | 'HIU', 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:** * transaction id is not provided or invalid * token or other auth confirmation details not provided or invalid
- `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)