docs: add reset password one-time token guide (#1445)

Author: charIeszhao

docs/end-user-flows/one-time-token.mdx

@@ -18,6 +18,7 @@ Logto supports the following scenarios with magic links:
 - **Invitation-only registration**: For internal tools or AI products in testing phase, you can disable public registration and invite specific users via magic links.
 - **Organization member invitation**: For SaaS products, use magic links to invite new members to join an organization, streamlining the onboarding process.
 - **Sign-in / Sign-up**: Send a magic link for passwordless sign-in or sign-up via email.
+- **Password reset**: Send a reset-password magic link from your own application so the user can verify the one-time token and set a new password in Logto.
 
 For example, when you've disabled public registration, you can send a magic link with a one-time token (e.g., `https://yourapp.com/landing-page?token=YHwbXSXxQfL02IoxFqr1hGvkB13uTqcd&email=user@example.com`) to the user's email to invite them to complete account creation. You can customize the email template in your own email delivery service, such as:
 
@@ -28,7 +29,6 @@ For example, when you've disabled public registration, you can send a magic link
 
 Currently not supported:
 
-- Password reset with magic link.
 - Using phone number or username as the identifier.
 
 ## One-time token flow \{#one-time-token-flow}
@@ -80,10 +80,24 @@ Sample request body payload:
 }
 ```
 
+For a password reset magic link, restrict the token to the forgot password flow:
+
+```json
+{
+  "email": "user@example.com",
+  "expiresIn": 3600,
+  "context": {
+    "interactionEvent": "ForgotPassword"
+  }
+}
+```
+
 ### Step 2: Compose your magic link \{#step-2-compose-your-magic-link}
 
 After you get the one-time token, you can compose a magic link and send it to the end user's email address.
-The magic link should at least contain the token and the user email as parameters, and should navigate to a landing page in your own application.
+For sign-in or sign-up magic links, the magic link should at least contain the token and the user email as parameters.
+For password reset magic links, the email parameter is optional; if you omit it, Logto will ask the user to enter their email address before verifying the one-time token.
+The magic link should navigate to a landing page in your own application.
 E.g. `https://yourapp.com/landing-page`.
 
 Here's a simple example of what the magic link may look like:
@@ -102,6 +116,8 @@ as well as encoding all the URL parameters.
 
 ### Step 3: Trigger the authentication flow via Logto SDK \{#step-3-trigger-the-authentication-flow-via-logto-sdk}
 
+#### Sign-in or sign-up \{#sign-in-or-sign-up}
+
 After the end user clicks the magic link and navigated to your application, you can extract the `token` and `email` parameters from the URL, and then call the `signIn()` function from Logto SDK to trigger the auth flow.
 
 ```typescript title="TokenLandingPage.tsx"
@@ -138,6 +154,42 @@ const TokenLandingPage = () => {
 };
 ```
 
+#### Reset password \{#reset-password}
+
+For password reset magic links, start an authentication request with `first_screen` set to `reset_password`.
+Pass the one-time token through `one_time_token`.
+If you already have the user's email from your landing page, pass it through `login_hint`; otherwise, omit `login_hint` and Logto will ask the user to enter their email address before token verification.
+
+```typescript title="ResetPasswordTokenLandingPage.tsx"
+// React example
+import { useLogto } from '@logto/react';
+import { useEffect } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+const ResetPasswordTokenLandingPage = () => {
+  const { signIn } = useLogto();
+  const [searchParams] = useSearchParams();
+
+  useEffect(() => {
+    const oneTimeToken = searchParams.get('token');
+    const email = searchParams.get('email');
+
+    if (oneTimeToken) {
+      signIn({
+        redirectUri: 'https://yourapp.com/callback',
+        extraParams: {
+          'one_time_token': oneTimeToken,
+          'first_screen': 'reset_password',
+          ...(email && { 'login_hint': email }),
+        },
+      });
+    }
+  }, [searchParams, signIn]);
+
+  return <>Please wait...</>;
+};
+```
+
 :::warning
 
 If a user is already signed-in, calling the`signIn()` function from SDK will automatically clear all cached tokens (ID token, access token, and refresh token) from client storage,

docs/end-user-flows/sign-up-and-sign-in/reset-password.mdx

@@ -95,6 +95,10 @@ You can implement your own password reset flow by using the Logto's **Management
 
 </summary>
 
-You can create a self-hosted password reset endpoint and utilize the Logto SDK to initiate a sign-in request with [`first_screen`](/end-user-flows/authentication-parameters/first-screen) set to `reset-password`. This will seamlessly redirect the user to the password reset page.
+You can create a self-hosted password reset endpoint and use the Logto SDK to initiate a sign-in request with [`first_screen`](/end-user-flows/authentication-parameters/first-screen) set to `reset_password`. This redirects the user to the password reset page.
+
+To verify the user with a magic link, create a [one-time token](/end-user-flows/one-time-token) for the user's email and pass it through the `one_time_token` authentication parameter. If you include `login_hint`, Logto will verify the token immediately; otherwise, Logto will ask the user to enter their email address before token verification.
+
+Learn more in the [one-time token password reset guide](/end-user-flows/one-time-token#reset-password).
 
 </details>