Skip to main content

Client Trust

Client Trust is Clerk's defense against credential stuffing attacks - a type of attack where bad actors use lists of stolen passwords to attempt to gain unauthorized access to user accounts.

When Client Trust is enabled, Clerk treats every new device as untrusted until the user has verified their identity with a .

How Client Trust works

Client Trust automatically requires a when all of the following conditions are met:

  1. The user enters a valid password.
  2. The user hasn't enabled multi-factor authentication (MFA).
  3. The user is signing in from a new device.

When these conditions are met, Clerk uses an email code, SMS code, or email link based on your settings. The user must complete this verification to finish the sign-in process.

Note

If the user has already enabled MFA (such as an authenticator app or SMS verification), Client Trust will not trigger - their existing MFA method will be used instead.

Enable Client Trust

Client Trust is automatically enabled for Clerk applications created after November 14, 2025. For applications created before this date, you can enable Client Trust in the Clerk Dashboard:

  1. In the Clerk Dashboard, navigate to the Attack protection page.
  2. Enable Client Trust.

Note

Client Trust requires password-based sign-in to be enabled.

How Client Trust differs from traditional MFA

AspectClient TrustTraditional MFA
TriggerAutomatic on new devicesUser must enable it
Verification methodEmail code, SMS code, or email linkTOTP, SMS code, backup codes
User setup requiredNoneUser must configure their preferred method
When it appliesOnly for password sign-insAll sign-ins

Impact on custom sign-in flows

If you've built a that allows password-based sign-ins using the Clerk API or SDKs, you'll need to handle the needs_client_trust status that Client Trust can trigger.

Note

If an older application has Client Trust enabled but your custom sign-in flow receives the legacy needs_second_factor status instead of needs_client_trust, opt in to the Client Trust Status update on the Updates page. This update doesn't enable Client Trust. It only changes the custom-flow response from needs_second_factor to needs_client_trust.

When Client Trust requires verification, the sign-in attempt will return a status of needs_client_trust with email_code, phone_code, or email_link in the supportedSecondFactors array. Your flow should:

  1. Check if the sign-in status is needs_client_trust.
  2. Check if email_code, phone_code, or email_link is in the supportedSecondFactors array.
  3. Call prepareSecondFactor() for the selected strategy.
  4. Complete the selected strategy's verification.
  5. If successful, set the session as active.

For a complete implementation example, see the email/password custom flow guide.

Tip

If your application supports both Client Trust and user-enabled MFA, make sure to handle both the needs_client_trust and needs_second_factor statuses. The needs_client_trust status is returned when Client Trust triggers on a new device, while needs_second_factor is returned when the user has MFA enabled on their account.

Limitations

  • Password-only: Client Trust only applies to password-based sign-ins. Passwordless authentication methods (such as email link sign-ins, , passkeys, and OAuth) are not affected.
  • Email/Phone number required: Client Trust requires the user to have a verified email address or phone number to receive the verification.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub