Validate TOTP

🔐 Validate TOTP API

This API allows enterprise applications to validate a Time-based One-Time Password (TOTP) submitted by a user. The TOTP is generated in the REL-ID mobile app and is used for authentication or identity confirmation.

🔗 Endpoint

POST https://REL-ID-SERVER-IP:9442/v1/validate-totp

🔐 Authorization

Authorization: Bearer <access_token>
Content-Type: application/json

📥 Request Body

{
  "userId": "u1",
  "totp": "Base64_SHA256_Encoded_TOTP"
}

Field	Type	Required	Description
`userId`	String	✅ Yes	REL-ID user ID to validate the TOTP for.
`totp`	String	✅ Yes	TOTP value (Base64 encoded SHA-256 hash).

✅ Success Responses

HTTP Code	Condition	Message
`200 OK`	Fresh TOTP	`"TOTP matched"`
`200 OK`	Replay TOTP matched	`"Replay TOTP matched"`

❌ Error Responses

🔍 404 - User Not Found

{
  "timeStamp": "2023-05-30T12:33:32IST",
  "status": 404,
  "error": "Data not present.",
  "message": "User not found.",
  "path": "/v1/validate-totp"
}

⚠️ 422 - Invalid or Missing Fields

{
  "timeStamp": "2023-05-30T12:33:32IST",
  "status": 422,
  "error": "Invalid data.",
  "message": "userId is invalid.",
  "path": "/v1/validate-totp"
}

{
  "timestamp": "2023-05-30T12:33:32IST",
  "status": 422,
  "error": "Invalid data.",
  "message": "User is not registered for TOTP.",
  "path": "/v1/validate-totp"
}

{
  "timestamp": "2023-06-20T10:45:11UTC",
  "status": 422,
  "error": "Invalid data.",
  "message": "TOTP matching failed",
  "path": "/v1/validate-totp"
}

🚫 409 - User Not Active

{
  "timestamp": "2023-06-20T10:46:21UTC",
  "status": 409,
  "error": "Not Active",
  "message": "validateTOTP is not allowed if user is in status BLOCKED",
  "path": "/v1/validate-totp"
}

💥 500 - Server Error

{
  "timeStamp": "2023-05-30T12:33:32IST",
  "status": 500,
  "error": "Internal Server Error",
  "message": "Unexpected error occurred while processing request",
  "path": "/v1/validate-totp"
}

📌 Notes

Supported hashing: SHA-256 (TOTP must be Base64 encoded)
Make sure the user's status is ACTIVE before invoking this API
Used TOTP values can still succeed but will return "Replay TOTP matched"

Updated 10 months ago