Account Blocking

🔍 Definitions

Term	Meaning
User Lock	Temporary restriction applied to the user's identity due to failed authentication attempts. Can retry after cooling period.
Device Lock	Temporary restriction applied to a specific device. The user can retry on the same device after the cooling period expires.
User Block	Permanent restriction on the user's account after all cooling periods are exhausted. Requires reset (manual or via SDK).
Device Block	Permanent restriction on a specific device. User cannot proceed from that device unless unblocked.

The behavior is driven by the cooling.period.locking.policy which determines whether lock/block is applied at user or device level.

🧊 Cooling Period

What is a Cooling Period?

A cooling period is a system-enforced wait time applied after a set of failed authentication attempts. It is defined by default.cooling.period.list in the Ditto ID configuration (e.g., 30,60,90 minutes).

If cooling period is not enabled, user is blocked immediately after retry limit.

Progressive Behavior

Ditto ID supports progressive lockouts using a configurable list like 30,60,90. Here's how it works:

Failure Cycle	Lockout Duration	Result
1st 5 failures	30 minutes	Temporarily locked
2nd 5 failures	60 minutes	Locked again
3rd 5 failures	90 minutes	Last interval
4th set	Blocked	Requires `resetBlockedUserAccount` or admin support

Cooling period behavior for different challenges

Failure Type	Cooling Response	After Final Interval
Password / Selfie Biometrics	Cooling applied → Retry later	User/Device is BLOCKED
OTP / Email / SMS / Custom Challenges	Cooling applied	Remains on last interval, not blocked
LDA (Face ID / Touch ID)	Controlled by OS	Not affected by SDK cooling config

UI Responsibilities

Disable retry actions during cooling period.

Read and compare deviceManagementCoolingPeriodEndTimestamp:

const isCoolingActive = Date.now() < deviceManagementCoolingPeriodEndTimestamp;

Show user message: "Too many failed attempts. Please try again at 3:30 PM."
Do not attempt auto-retry. Wait for period to expire.

🔓 Unblocking Users Using `resetBlockedUserAccount`

When is it allowed?

You may call resetBlockedUserAccount() only when the SDK response hasstatusCode = 141.

Status Code	Message	Meaning	Can Call Reset?
`141`	Your user/device is blocked, would you like to proceed with reactivation of this device?	User is blocked but eligible for self-reset	✅ Yes
`138`	User Device is blocked. Kindly contact the admin.	User is blocked and must contact admin	❌ No
`166`	User is locked. Please try again after REMAINING_TIME	User is temporarily locked	❌ No (wait for cooldown)

Example: React Native

if (statusCode === 141) {
  RdnaClient.resetBlockedUserAccount((res) => {
    if (res.success) {
      // Proceed with login/activation
    } else {
      showMessage("Failed to unblock. Please try again.");
    }
  });
}

Do not call the reset API for any status other than 141.

🔁 API Summary

API	When to Use	Notes
`getUser`, `authenticateUserAndSignData`, `setPassword`	To detect status codes and challenge failures	Parse `statusCode` in the callback
`onGetRegisteredDeviceDetails`	To check cooling period via timestamp	Inspect `deviceManagementCoolingPeriodEndTimestamp`
`resetBlockedUserAccount`	When `statusCode === 141`	Resets block, allows user to proceed

Updated 4 months ago