Validate OTP

Validate a previously generated One-Time Password (OTP).

This API verifies the OTP entered by the user against the OTP generated using the Generate OTP API. If the OTP is valid, the response indicates a successful validation. If generateJwt was set to true when generating the OTP, a JWT may also be returned.

📘
Prerequisite
Before calling this API, you must successfully generate an OTP using the Generate OTP API and retain the returned otpUuid.

Endpoint

PUT /v1/relid-otp

Authentication

Include a Bearer token in the request header.

Authorization: Bearer <access_token>

Request Body

Field	Type	Required	Description
`otpUuid`	string	✅	Unique identifier returned by the Generate OTP API.
`otpValue`	string	✅	OTP value entered by the user. The value must be hashed using the same hash algorithm used during OTP generation.

Example Request

{
  "otpUuid": "6c677c1e-e78e-4e19-a77c-1ee78efe1998",
  "otpValue": "1f40fc92da241694750979ee6cf582f2..."
}

Field Details

otpUuid

The unique OTP identifier returned by the Generate OTP API.

This value associates the validation request with a previously generated OTP.

otpValue

The OTP entered by the user.

The value must be hashed using the same hashSpec that was specified when the OTP was generated.

Success Response

A successful validation returns HTTP 200.

Validation Successful

{
  "otpUuid": "6c677c1e-e78e-4e19-a77c-1ee78efe1998",
  "validationStatus": "SUCCESS",
  "expiryTs": 1739964200556,
  "jwt": "<JWT>",
  "jwtStatus": "GENERATED"
}

Field	Description
`otpUuid`	OTP identifier.
`validationStatus`	Validation result. Returns `SUCCESS`.
`expiryTs`	OTP expiry timestamp (Epoch milliseconds).
`jwt`	JWT returned when `generateJwt=true` during Generate OTP.
`jwtStatus`	JWT generation status (`GENERATED` or `FAILED`).

📘
Note
The jwt and jwtStatus fields are returned only when generateJwt was enabled during the Generate OTP request.

Validation Failed

The API still returns HTTP 200 when validation fails.

{
  "otpUuid": "6c677c1e-e78e-4e19-a77c-1ee78efe1998",
  "validationStatus": "FAILED",
  "attemptsLeft": 8,
  "expiryTs": 1740050600556
}

Field	Description
`validationStatus`	Returns `FAILED`.
`attemptsLeft`	Number of validation attempts remaining.
`expiryTs`	OTP expiry timestamp (Epoch milliseconds).

Error Responses

HTTP Status	Description
400	Missing mandatory fields.
404	OTP UUID not found.
422	Invalid OTP UUID or invalid OTP value.

Example - Missing mandatory fields

{
  "timestamp": "2025-02-20T09:27:25IST",
  "status": 400,
  "error": "Bad Request",
  "message": "Mandatory fields are missing",
  "path": "/v1/relid-otp"
}

Example - Invalid OTP

{
  "timestamp": "2025-02-20T09:00:26IST",
  "status": 422,
  "error": "Invalid data",
  "message": "Invalid OTP",
  "path": "/v1/relid-otp"
}

Example - OTP UUID Not Found

{
  "timestamp": "2025-02-20T09:27:25IST",
  "status": 404,
  "error": "Data not present.",
  "message": "otpUuid not found",
  "path": "/v1/relid-otp"
}

Best Practices

Store the otpUuid returned by the Generate OTP API until validation is complete.
Hash the OTP using the same hashSpec used during OTP generation.
Handle both SUCCESS and FAILED validation responses, even though both return HTTP 200.
If attemptsLeft reaches zero, generate a new OTP.
If a JWT is expected, verify that jwtStatus is GENERATED before using the returned JWT.

Updated 28 days ago

Did this page help you?