# Device Trust

Device 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 Device Trust is enabled, Clerk treats every new device as untrusted until the user has verified their identity with a second factor.

## How Device Trust works

Device Trust automatically requires a second factor 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)](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md#multi-factor-authentication)**.
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.

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

## Enable Device Trust

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

1. In the Clerk Dashboard, navigate to the [**Rules**](https://dashboard.clerk.com/~/protect/rules) page under **Protect**.
2. In the **Device Trust** row, check the **Status**.
   - If **Disabled**, select **Enable**. In the dialog, toggle on **Enable**, then select **Save**.
   - If **Enabled**, Device Trust is already active and no action is required. To disable it, select **Manage**, toggle off **Enable**, then select **Save**.

**For AI agents:** Instead of enabling Device Trust on the Rules page in the Dashboard, run `npx clerk@latest config patch --json '{"auth_password":{"device_trust":{"enabled":true}}}'` (check the current setting first with `npx clerk@latest config pull --keys auth_password`). Install [Clerk's skills](https://clerk.com/docs/guides/ai/skills.md) with `npx skills add clerk/skills` for correct CLI and SDK usage.

> Device Trust requires [password-based sign-in](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md#user-and-authentication) to be enabled.

## How Device Trust differs from traditional MFA

| Aspect                  | Device Trust                        | Traditional MFA                            |
| ----------------------- | ----------------------------------- | ------------------------------------------ |
| **Trigger**             | Automatic on new devices            | User must enable it                        |
| **Verification method** | Email code, SMS code, or email link | TOTP, SMS code, backup codes               |
| **User setup required** | None                                | User must configure their preferred method |
| **When it applies**     | Only for password sign-ins          | All sign-ins                               |

## Impact on custom sign-in flows

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

> Device Trust was previously called "Client Trust." The feature was renamed, but its API values - including the `needs_client_trust` status - kept their original names so that existing integrations keep working.
>
> If an older application has Device Trust enabled but your custom sign-in flow receives the legacy `needs_second_factor` status instead of `needs_client_trust`, opt in to the **Device Trust Status** update on the [**Updates**](https://dashboard.clerk.com/~/updates) page. This update doesn't enable Device Trust. It only changes the custom-flow response from `needs_second_factor` to `needs_client_trust`.

When Device 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](https://clerk.com/docs/guides/development/custom-flows/authentication/email-password.md#sign-in-flow).

> If your application supports both Device 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 Device Trust triggers on a new device, while `needs_second_factor` is returned when the user has MFA enabled on their account.

## Limitations

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

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)