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 Ditto 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	Ditto 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"