Forgot Password

Endpoint Overview

POST /api/v1/itr/forget-password

Description

This endpoint facilitates password reset functionality for users who have forgotten their passwords. When a user submits their client ID and a new password, the system validates the password against security requirements and sends a one-time password (OTP) to the user's registered mobile number for verification. This two-factor authentication approach ensures secure password reset while maintaining user account integrity.

Key Benefits

Secure two-factor authentication using OTP verification

Self-service password recovery without administrator intervention

Enforced password complexity requirements for enhanced security

Immediate password reset capability with real-time OTP delivery

Use Cases

Financial Services

Tax Filing

Identity Verification

Enable customers to securely reset passwords for banking and investment applications

Allow financial advisors to regain access to client management systems

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 for authentication (JWT format)
Content-Type	Yes	application/json

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier of the user account
password	String	Yes	New password that meets complexity requirements

Password Requirements

The new password must meet the following criteria:

Length: 8-14 characters

Must contain at least one uppercase letter

Must contain at least one lowercase letter

Must contain at least one number

Must contain at least one special character (e.g., @, #, $, %)

Example Request

{
    "client_id": "itr_hIljWFhdruRxPAPTGzQs",
    "password": "rashal@2001"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Contains the response data
data.otp_sent	Boolean	Indicates whether the OTP was successfully sent
status_code	Integer	HTTP status code of the response
message_code	String	Brief status description
message	String	Detailed status message
success	Boolean	Overall success status of the request

Example Successful Response

{
    "data": {
        "otp_sent": true
    },
    "status_code": 200,
    "message_code": "success",
    "message": "OTP Sent",
    "success": true
}

Possible Error Responses

Invalid Password Format

Invalid Client ID

Authentication Error

{
    "data": null,
    "status_code": 400,
    "message_code": "error",
    "message": "Password does not meet complexity requirements",
    "success": false
}

The provided password does not meet the required complexity criteria.

Integration Best Practices

Security Recommendations

Implement rate limiting to prevent brute force attacks

Use HTTPS for all API communications to ensure data encryption

Store the client_id securely and never expose it in client-side code

Implement proper error handling to avoid leaking sensitive information

User Experience Guidelines

Clearly communicate password requirements to users before submission

Provide immediate feedback when password requirements are not met

Implement a countdown timer for OTP expiration to set user expectations

Offer a resend OTP option in case of delivery issues

Code Samples

cURL

Python

Node.js

Related APIs

Verify OTP: Validates the OTP sent during password reset

Login: Authenticates users with their credentials

Change Password: Allows authenticated users to change their password

User Profile: Retrieves and updates user profile information

Compliance and Legal Considerations

This API handles sensitive user authentication data and must be implemented in compliance with data protection regulations such as GDPR, CCPA, or other applicable regional laws. Ensure proper consent mechanisms are in place for collecting and processing user data, and implement appropriate data retention policies.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/itr/forget-password' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "itr_hIljWFhdruRxPAPTGzQs", "password": "rashal@2001" }'

Forgot Password

Forgot Password#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Password Requirements#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

Forgot Password

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Password Requirements

Example Request

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples