Add password reset task documentation and error handling updates

- Introduced a new section in the session tasks guide for the password reset task, including its key and description.
- Added error handling details for compromised passwords in the custom flows documentation.
- Documented the `<TaskResetPassword />` component for rendering the password reset UI.
- Updated the password protection guide to include instructions for manually marking passwords as compromised.

Author: octoper

docs/guides/configure/session-tasks.mdx

@@ -14,6 +14,7 @@ The following table lists the available tasks and their corresponding keys.
 | Setting | Key | Description |
 | - | - | - |
 | [Allow Personal Accounts](https://dashboard.clerk.com/~/organizations-settings) | `choose-organization` | Disabled by default when enabling Organizations. When disabled, users are required to choose an Organization after authenticating. When enabled, users can choose a Personal Account instead of an Organization. |
+| [Password reset](/docs/reference/components/authentication/task-reset-password) | `reset-password` | When the user is required to reset their password on their next sign-in. |
 
 ## Session states
 
@@ -34,6 +35,7 @@ The following table lists the available tasks and their corresponding components
 | Name | Component |
 | - | - |
 | [Personal accounts disabled (default)](/docs/guides/organizations/overview#allow-personal-accounts) | [`<TaskChooseOrganization />`](/docs/reference/components/authentication/task-choose-organization) |
+| Password reset | [`<TaskResetPassword />`](/docs/reference/components/authentication/task-reset-password) |
 
 > [!IMPORTANT]
 > Personal accounts being disabled by default was released on 08-22-2025. Applications created before this date will not be able to see the **Allow Personal Accounts** setting, because Personal Accounts were enabled by default.

docs/guides/development/custom-flows/error-handling.mdx

@@ -271,3 +271,280 @@ For instance, if you wish to inform a user at which absolute time they will be a
     ```
   </Tab>
 </Tabs>
+
+### Password compromised
+
+If you have marked a user's password as compromised and they have another identification method to sign-in, you will receive an HTTP status of `422 (Unprocessable Entity)` and the following error payload:
+
+```json
+{
+  "errors": [
+    {
+      "message": "Password compromised",
+      "long_message": "Your password appears to have been compromised or it's no longer trusted and cannot be used. Please use another method to continue.",
+      "code": "form_password_compromised",
+      "meta": {
+        "name": "param"
+      }
+    }
+  ]
+}
+```
+
+When a user password is marked as compromised, they will not be able to sign in with their compromised password, so you should prompt them to sign-in with another method. If they do not have any other identification methods to sign-in, e.g if they only have username and password, they will be signed in but they will be required to reset their password.
+
+<Tabs items={["Next.js"]}>
+  <Tab>
+      This example is written for Next.js App Router but it can be adapted for any React-based framework.
+
+      ```tsx {{ filename: 'app/sign-in/page.tsx' }}
+      "use client";
+
+      import * as React from "react";
+      import { useSignIn } from "@clerk/nextjs";
+      import { useRouter } from "next/navigation";
+      import {
+        ClerkAPIError,
+        EmailCodeFactor,
+        SignInFirstFactor,
+      } from "@clerk/types";
+      import { isClerkAPIResponseError } from "@clerk/nextjs/errors";
+
+      const SignInWithEmailCode = () => {
+        const { isLoaded, signIn, setActive } = useSignIn();
+        const [errors, setErrors] = React.useState<ClerkAPIError[]>();
+        const [verifying, setVerifying] = React.useState(false);
+        const [email, setEmail] = React.useState("");
+        const [code, setCode] = React.useState("");
+        const router = useRouter();
+
+        async function handleSubmit(e: React.FormEvent) {
+          e.preventDefault();
+
+          if (!isLoaded && !signIn) return null;
+
+          try {
+            // Start the sign-in process using the email code method
+            const { supportedFirstFactors } = await signIn.create({
+              identifier: email,
+            });
+
+            // Filter the returned array to find the 'email_code' entry
+            const isEmailCodeFactor = (
+              factor: SignInFirstFactor
+            ): factor is EmailCodeFactor => {
+              return factor.strategy === "email_code";
+            };
+            const emailCodeFactor = supportedFirstFactors?.find(isEmailCodeFactor);
+
+            if (emailCodeFactor) {
+              // Grab the emailAddressId
+              const { emailAddressId } = emailCodeFactor;
+
+              // Send the OTP code to the user
+              await signIn.prepareFirstFactor({
+                strategy: "email_code",
+                emailAddressId,
+              });
+
+              // Set verifying to true to display second form
+              // and capture the OTP code
+              setVerifying(true);
+            }
+          } catch (err) {
+            // See https://clerk.com/docs/guides/development/custom-flows/error-handling
+            // for more info on error handling
+            console.error("Error:", JSON.stringify(err, null, 2));
+          }
+        }
+
+        async function handleVerification(e: React.FormEvent) {
+          e.preventDefault();
+
+          if (!isLoaded && !signIn) return null;
+
+          try {
+            // Use the code provided by the user and attempt verification
+            const signInAttempt = await signIn.attemptFirstFactor({
+              strategy: "email_code",
+              code,
+            });
+
+            // If verification was completed, set the session to active
+            // and redirect the user
+            if (signInAttempt.status === "complete") {
+              await setActive({
+                session: signInAttempt.createdSessionId,
+                navigate: async ({ session }) => {
+                  if (session?.currentTask) {
+                    // Check for tasks and navigate to custom UI to help users resolve them
+                    // See https://clerk.com/docs/guides/development/custom-flows/overview#session-tasks
+                    console.log(session?.currentTask);
+                    return;
+                  }
+
+                  router.push("/");
+                },
+              });
+            } else {
+              // If the status is not complete, check why. User may need to
+              // complete further steps.
+              console.error(signInAttempt);
+            }
+          } catch (err) {
+            // See https://clerk.com/docs/guides/development/custom-flows/error-handling
+            // for more info on error handling
+            console.error("Error:", JSON.stringify(err, null, 2));
+          }
+        }
+
+        if (verifying) {
+          return (
+            <>
+              <h1>Verify your email address</h1>
+              <form onSubmit={handleVerification}>
+                <label htmlFor="code">Enter your email verification code</label>
+                <input
+                  value={code}
+                  id="code"
+                  name="code"
+                  onChange={(e) => setCode(e.target.value)}
+                />
+                <button type="submit">Verify</button>
+              </form>
+            </>
+          );
+        }
+
+        return (
+          <>
+            <form onSubmit={handleSubmit}>
+              <label htmlFor="email">Enter email address</label>
+              <input
+                value={email}
+                id="email"
+                name="email"
+                type="email"
+                onChange={(e) => setEmail(e.target.value)}
+              />
+              <button type="submit">Continue</button>
+            </form>
+
+            {errors && (
+              <ul>
+                {errors.map((el, index) => (
+                  <li key={index}>{el.longMessage}</li>
+                ))}
+              </ul>
+            )}
+          </>
+        );
+      };
+
+      export default function SignInForm() {
+        const { isLoaded, signIn, setActive } = useSignIn();
+        const [email, setEmail] = React.useState("");
+        const [password, setPassword] = React.useState("");
+        const [errors, setErrors] = React.useState<ClerkAPIError[]>();
+
+        const router = useRouter();
+
+        // Handle the submission of the sign-in form
+        const handleSignInWithPassword = async (e: React.FormEvent) => {
+          e.preventDefault();
+
+          // Clear any errors that may have occurred during previous form submission
+          setErrors(undefined);
+
+          if (!isLoaded) {
+            return;
+          }
+
+          // Start the sign-in process using the email and password provided
+          try {
+            const signInAttempt = await signIn.create({
+              identifier: email,
+              password,
+            });
+
+            // If sign-in process is complete, set the created session as active
+            // and redirect the user
+            if (signInAttempt.status === "complete") {
+              await setActive({
+                session: signInAttempt.createdSessionId,
+                navigate: async ({ session }) => {
+                  if (session?.currentTask) {
+                    // Check for tasks and navigate to custom UI to help users resolve them
+                    // See https://clerk.com/docs/guides/development/custom-flows/overview#session-tasks
+                    console.log(session?.currentTask);
+                    return;
+                  }
+
+                  router.push("/");
+                },
+              });
+            } else {
+              // If the status is not complete, check why. User may need to
+              // complete further steps.
+              console.error(JSON.stringify(signInAttempt, null, 2));
+            }
+          } catch (err) {
+            if (isClerkAPIResponseError(err)) setErrors(err.errors);
+            console.error(JSON.stringify(err, null, 2));
+          }
+        };
+
+        if (errors && errors[0].code === "form_password_compromised") {
+          return (
+            <>
+              <h1>Sign in</h1>
+
+              <p>Your password appears to have been compromised or it&apos;s no longer trusted and cannot be used. Please use email code to continue.</p>
+
+              <SignInWithEmailCode />
+            </>
+          );
+        }
+
+        // Display a form to capture the user's email and password
+        return (
+          <>
+            <h1>Sign in</h1>
+
+            <form onSubmit={(e) => handleSignInWithPassword(e)}>
+              <div>
+                <label htmlFor="email">Enter email address</label>
+                <input
+                  onChange={(e) => setEmail(e.target.value)}
+                  id="email"
+                  name="email"
+                  type="email"
+                  value={email}
+                />
+              </div>
+              <div>
+                <label htmlFor="password">Enter password</label>
+                <input
+                  onChange={(e) => setPassword(e.target.value)}
+                  id="password"
+                  name="password"
+                  type="password"
+                  value={password}
+                />
+              </div>
+              <button type="submit">Sign in</button>
+            </form>
+
+            {errors && (
+              <ul>
+                {errors.map((el, index) => (
+                  <li key={index}>{el.longMessage}</li>
+                ))}
+              </ul>
+            )}
+          </>
+        );
+      }
+      ```
+    </Tab>
+</Tabs>

docs/guides/development/errors/frontend-api.mdx

@@ -3316,3 +3316,17 @@ link has expired.
   "code": "waitlist_not_accepting_entries"
 }
 ```
+
+### <code><wbr />Form<wbr />Pwned<wbr />Password</code>
+
+`FormPwnedPassword` signifies an error when the chosen password has been found in the pwned list
+
+```json {{ filename: 'Status Code: 422' }}
+{
+  "longMessage": "Your password appears to have been compromised or it's no longer trusted and cannot be used. Please use another method to continue.",
+  "code": "form_password_compromised",
+  "meta": {
+    "name": "param"
+  }
+}
+```

docs/guides/secure/password-protection-and-rules.mdx

@@ -49,3 +49,27 @@ For users that set an average/weak password that complies with your organization
 
 > [!NOTE]
 > OWASP recommends providing feedback to users on the strength of their password and offering suggestions for improvement. This can help users create stronger passwords and improve the overall security of the application.
+
+## Manually marking passwords as compromised
+
+Clerk provides a way to manually mark passwords as compromised. This is useful for blocking passwords in the case that:
+
+- The password has recently been added to the compromised password database
+- The user was able to set a compromised password because protection was off at the time
+
+> [!NOTE]
+> This action will require the user to create a new password on their next sign-in.
+> If you are implementing custom authentication flows, you will need to handle the compromised password flow by yourself. See [Error handling](/docs/guides/development/custom-flows/error-handling#password-compromised) for more information.
+> If your instance is older than December 8th 2025, you will need to update your instance to the **Reset password session task** update.
+> 1. In the Clerk Dashboard, navigate to [**Updates**](https://dashboard.clerk.com/~/updates) page.
+> 2. Find the **Reset password session task**, check if the SDK versions mentioned are the ones you are using, if not you will first need to upgrade your SDK's to at least the version's mentioned.
+> 3. Once you have upgraded your SDK's, you can update to use the **Reset password session task** by clicking the **Update** button.
+
+To manually mark a user's password as compromised:
+
+1. In the Clerk Dashboard, navigate to [**Users**](https://dashboard.clerk.com/~/users) page and find the user you want to mark as compromised.
+1. Click the user's profile and in the password section, if a password is set, you will find the **Mark password as compromised** action, under the three dots menu.
+1. Click the **Mark password as compromised** action and a confirmation dialog will appear.
+1. You will need to type "Compromised" to confirm the action.
+1. Click the **Confirm** button and the user's password will be marked as compromised.
+1. Now the user will not be able to sign in with their existing password and will need to create a new password on their next sign-in.