Submit OTP

Endpoint Overview

POST /api/v1/itr/submit-otp

Description

This endpoint allows users to submit the one-time password (OTP) received during the password reset process, along with the unique client ID. Upon successful validation, the system completes the password reset process, enabling users to regain access to their accounts with a new password.

Key Benefits

Secure two-factor authentication for password reset

Simple implementation with minimal required parameters

Immediate confirmation of password reset status

Enhanced security through unique client ID verification

Use Cases

Financial Services

Government Services

Enterprise Solutions

Secure password recovery for banking and investment applications

Enabling customers to regain access to tax filing platforms

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token authentication using JWT
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
otp	String	Yes	The one-time password received during the password reset process
client_id	String	Yes	Unique identifier provided in the previous step of the password reset flow

Example Request

{
    "otp": "232493",
    "client_id": "itr_hIljWFhdruRxPAPTGzQs"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.password_reset	Boolean	Indicates whether the password was successfully reset
status_code	Integer	HTTP status code of the response
message_code	String	Short code indicating the result of the operation
message	String	Human-readable description of the operation result
success	Boolean	Overall success status of the API call

Example Successful Response

{
    "data": {
        "password_reset": true
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Password reset successful",
    "success": true
}

Possible Error Responses

Invalid OTP

Invalid Client ID

{
    "data": {
        "password_reset": false
    },
    "status_code": 400,
    "message_code": "invalid_otp",
    "message": "The OTP provided is invalid or has expired",
    "success": false
}

The OTP provided is incorrect or has expired. Users typically have a limited time window to use an OTP.

Integration Best Practices

Security Recommendations

Store client_id securely and temporarily during the password reset flow

Implement proper error handling to prevent revealing sensitive information

Add rate limiting to prevent brute force attacks on the OTP submission

Set appropriate OTP expiration times (typically 5-10 minutes)

User Experience Guidelines

Provide clear instructions to users about where to find the OTP (email, SMS)

Implement a resend OTP option if the user doesn't receive it

Display user-friendly error messages when OTP validation fails

Offer alternative recovery methods if users consistently fail OTP verification

Code Samples

cURL

Python

Node.js

Related APIs

Request OTP API - Initiates the password reset process and sends an OTP to the user

Reset Password API - Allows setting a new password after OTP verification

User Authentication API - Handles user login with the new password

Compliance and Legal Considerations

When implementing password reset functionality, ensure compliance with data protection regulations such as GDPR or CCPA. The OTP delivery method (SMS/email) may have specific regulatory requirements in certain jurisdictions. Maintain appropriate logs for security audit purposes while ensuring personal data is handled according to privacy policies.

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/itr/submit-otp' \ --header 'Content-Type: application/json' \ --data-raw '{ "otp": "232493", "client_id": "itr_hIljWFhdruRxPAPTGzQs" }'

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Submit OTP

Submit OTP#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Submit OTP

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples