wip

Author: alexisintech

docs/guides/development/custom-flows/authentication/client-trust.mdx

@@ -0,0 +1,33 @@
+---
+title: Build a custom authentication flow with Client Trust
+description: Learn how to build a custom authentication flow that supports Client Trust.
+---
+
+<Include src="_partials/custom-flows-callout" />
+
+<If sdk={["nextjs", "react", "expo", "js-frontend", "react-router", "tanstack-react-start"]}>
+  > [!IMPORTANT]
+  > This guide applies to the following Clerk SDKs:
+  >
+  > - `@clerk/react` v6 or higher
+  > - `@clerk/nextjs` v7 or higher
+  > - `@clerk/expo` v3 or higher
+  > - `@clerk/react-router` v3 or higher
+  > - `@clerk/tanstack-react-start` v0.26.0 or higher
+  >
+  > If you're using an older version of one of these SDKs, or are using the legacy API, refer to the [legacy API documentation](/docs/guides/development/custom-flows/authentication/legacy/email-password).
+</If>
+
+Client Trust is Clerk's defense against [credential stuffing](https://owasp.org/www-community/attacks/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, when a user is signing in with a password on a new client (e.g. device), users will always be challenged for a [second factor](!second-factor). If you have multi-factor authentication (MFA) enabled, users may have already configured a second factor, such as SMS verification code or authenticator app. If you don't have MFA enabled, or if the user has not yet configured one, a one-time email code (default), SMS code, or email link will be used, depending on your application's settings.
+
+This guide will demonstrate how to build a custom sign-in flow that supports the second factor strategies: email code and email link. To support SMS code or authenticator app, see the [MFA custom flow guide](/docs/guides/development/custom-flows/authentication/email-password-mfa).
+
+## Build the custom flow
+
+When Client Trust requires verification, the sign-in attempt will return a status of `needs_second_factor`.
+
+### Email code
+
+### Email link