For the complete documentation index, see llms.txt. This page is also available as Markdown.

Reset TOTP

Reset an end user's TOTP secret after device loss.

Resets an end user's TOTP secret after device loss. This flow does not require the current TOTP code.

The merchant backend requests an email code first. It then uses that code to rotate the TOTP secret. Never call these endpoints from a browser.

Authentication and requirements

Both endpoints require these headers:

x-tlp-apikey: <api-key>
x-tlp-signature: <hmac-signature>

Generate the signature using:

HMAC_SHA256(apiSecret, JSON.stringify(params))

For GET requests, params is the query object. For POST requests, it is the request body.

Send the query or body exactly as signed. Preserve field names, order, types, and values.

The merchant IP must be on its configured whitelist. An empty whitelist blocks every request.

The end user must meet these requirements:

  • Identify them with endUserId, externalUserId, or endUserEmail.

  • Their account must be active.

Every response uses this envelope:

{
  "msg": "",
  "data": {}
}

msg is empty on success unless stated otherwise. data contains the response payload.

Common authentication errors

HTTP status

msg

Cause

401

API key and signature headers (x-tlp-apikey, x-tlp-signature) are required.

A required authentication header is missing.

401

Invalid API key.

The API key was not found.

403

API key or owner is inactive.

The key or merchant account is inactive.

400

Invalid signature.

The HMAC signature does not match.

403

Whitelabel IP whitelist is not configured.

The merchant has no IP whitelist.

403

IP not whitelisted.

The caller IP is not allowed.

400

One of endUserEmail, endUserId or externalUserId is required.

No end-user identifier was supplied.

404

End user not found for this owner.

The user does not belong to this merchant.

403

End user is suspended.

The end-user account is suspended.

403

KYC not approved.

The end user's KYC status is not approved.

Step 1: Send a reset email code

Endpoint

Generates a six-digit code and emails it to the end user's registered email address. The code expires after five minutes.

Query parameters

Field
Required
Description

endUserId, externalUserId, or endUserEmail

One required

Identifies the end user who receives the code.

Sign the complete query object.

Example request

Successful response

The code is one-shot. Step 2 consumes it after a successful match.

Rate limit and errors

You can request at most five codes per end user every 15 minutes.

HTTP status

msg

Cause

429

Rate limit exceeded for sending OTP...

More than five requests within 15 minutes.

500

Unable to send code. Contact support

The user was not found, or Redis or SendGrid failed.

Step 2: Verify the code and reset TOTP

Endpoint

Verifies the email code and rotates the end user's TOTP secret. The previous secret becomes invalid immediately.

Request body

Field
Required
Description

endUserId, externalUserId, or endUserEmail

One required

Identifies the end user.

emailCode

Yes

The six-digit code sent in Step 1.

timestamp

Yes

Unix epoch milliseconds within ±120 seconds of server time.

nonce

Yes

A unique random value used once within the allowed window.

Include timestamp and nonce in the signed request body. Reusing a nonce returns 409 Conflict.

Example request

Code snippet

Run this example from the merchant's secure backend. It sends the email code, then resets TOTP after the end user provides that code.

Replace externalUserId with the relevant end-user identifier. Replace emailCode only after the end user supplies the emailed code.

Successful response

Response fields

Field
Type
Description

totpSecret

string

The new base32 TOTP secret.

totpQrCodeString

string

An otpauth:// URI for QR-code enrollment.

Treat both values as credentials. They are returned only by this reset request.

Securely deliver the QR code or secret to the relevant end user. Do not expose either value in logs or analytics.

Errors

HTTP status

msg

Cause

401

End user not resolved.

The middleware did not resolve an end user.

400

Parameter emailCode is mandatory.

emailCode is missing.

400

Access Denied! OTP does not match!

The code is incorrect or expired. A mismatch does not consume the code.

400

Unable to reset TOTP. Contact Support.

The user has no TOTP secret. A matching code is consumed.

400

Parameters timestamp and nonce are mandatory for this operation.

A replay-protection field is missing.

400

timestamp is outside the allowed window.

The timestamp is not within ±120 seconds.

409

Duplicate request detected (nonce already used).

The nonce was already used.

500

Failed to reset TOTP. Contact support.

The database write failed.

A matching email code is consumed immediately. This also applies if a later check fails. Request a new code if needed.

Successful resets are recorded in whitelabel_audit_log. The record includes the merchant ID, end-user ID, API-key authentication type, and client IP.

Recovery flow

  1. Call GET /whitelabel/auth/sendResetTotpOTP with an end-user identifier.

  2. Collect the emailed code through the merchant's own user experience.

  3. Call POST /whitelabel/auth/resetTotp with the code, timestamp, and nonce.

  4. Display the returned QR code for new authenticator enrollment.

The merchant cannot create the end user's email code. The end user must provide it through the merchant's user experience.

Last updated