feat(clerk-js,react,shared): Add support for reset password via phone code (#7824)

dstaley · web-flow · commit b971d0bb3eed · 2026-02-11T14:45:53.000-06:00
diff --git a/.changeset/lazy-eagles-lay.md b/.changeset/lazy-eagles-lay.md
@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/react': minor
+---
+
+Add support for resetting a password via phone code.
diff --git a/packages/clerk-js/src/core/resources/SignIn.ts b/packages/clerk-js/src/core/resources/SignIn.ts
@@ -48,6 +48,8 @@ import type {
   SignInFuturePasswordParams,
   SignInFuturePhoneCodeSendParams,
   SignInFuturePhoneCodeVerifyParams,
+  SignInFutureResetPasswordPhoneCodeSendParams,
+  SignInFutureResetPasswordPhoneCodeVerifyParams,
   SignInFutureResetPasswordSubmitParams,
   SignInFutureResource,
   SignInFutureSSOParams,
@@ -640,6 +642,12 @@ class SignInFuture implements SignInFutureResource {
     submitPassword: this.submitResetPassword.bind(this),
   };
 
+  resetPasswordPhoneCode = {
+    sendCode: this.sendResetPasswordPhoneCode.bind(this),
+    verifyCode: this.verifyResetPasswordPhoneCode.bind(this),
+    submitPassword: this.submitResetPassword.bind(this),
+  };
+
   phoneCode = {
     sendCode: this.sendPhoneCode.bind(this),
     verifyCode: this.verifyPhoneCode.bind(this),
@@ -751,6 +759,51 @@ class SignInFuture implements SignInFutureResource {
     });
   }
 
+  async sendResetPasswordPhoneCode(
+    params: SignInFutureResetPasswordPhoneCodeSendParams = {},
+  ): Promise<{ error: ClerkError | null }> {
+    const { phoneNumber } = params;
+    if (!this.#resource.id && !phoneNumber) {
+      throw new Error(
+        'signIn.resetPasswordPhoneCode.sendCode() cannot be called without a phoneNumber if an existing signIn does not exist.',
+      );
+    }
+
+    return runAsyncResourceTask(this.#resource, async () => {
+      if (phoneNumber) {
+        await this._create({ identifier: phoneNumber });
+      }
+
+      const resetPasswordPhoneCodeFactor = this.#resource.supportedFirstFactors?.find(
+        f => f.strategy === 'reset_password_phone_code',
+      );
+
+      if (!resetPasswordPhoneCodeFactor) {
+        throw new ClerkRuntimeError('Reset password phone code factor not found', {
+          code: 'factor_not_found',
+        });
+      }
+
+      const { phoneNumberId } = resetPasswordPhoneCodeFactor;
+      await this.#resource.__internal_basePost({
+        body: { phoneNumberId, strategy: 'reset_password_phone_code' },
+        action: 'prepare_first_factor',
+      });
+    });
+  }
+
+  async verifyResetPasswordPhoneCode(
+    params: SignInFutureResetPasswordPhoneCodeVerifyParams,
+  ): Promise<{ error: ClerkError | null }> {
+    const { code } = params;
+    return runAsyncResourceTask(this.#resource, async () => {
+      await this.#resource.__internal_basePost({
+        body: { code, strategy: 'reset_password_phone_code' },
+        action: 'attempt_first_factor',
+      });
+    });
+  }
+
   async submitResetPassword(params: SignInFutureResetPasswordSubmitParams): Promise<{ error: ClerkError | null }> {
     const { password, signOutOfOtherSessions = true } = params;
     return runAsyncResourceTask(this.#resource, async () => {
diff --git a/packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts b/packages/clerk-js/src/core/resources/__tests__/SignIn.test.ts
@@ -890,6 +890,133 @@ describe('SignIn', () => {
       });
     });
 
+    describe('sendResetPasswordPhoneCode', () => {
+      afterEach(() => {
+        vi.clearAllMocks();
+      });
+
+      it('creates signIn with phoneNumber when no existing signIn', async () => {
+        const mockFetch = vi
+          .fn()
+          .mockResolvedValueOnce({
+            client: null,
+            response: {
+              id: 'signin_123',
+              identifier: '+15551234567',
+              supported_first_factors: [
+                {
+                  strategy: 'reset_password_phone_code',
+                  phone_number_id: 'phone_123',
+                  safe_identifier: '+15551234567',
+                },
+              ],
+            },
+          })
+          .mockResolvedValueOnce({
+            client: null,
+            response: { id: 'signin_123' },
+          });
+        BaseResource._fetch = mockFetch;
+
+        const signIn = new SignIn();
+        await signIn.__internal_future.resetPasswordPhoneCode.sendCode({ phoneNumber: '+15551234567' });
+
+        expect(mockFetch).toHaveBeenNthCalledWith(1, {
+          method: 'POST',
+          path: '/client/sign_ins',
+          body: { identifier: '+15551234567' },
+        });
+
+        expect(mockFetch).toHaveBeenNthCalledWith(2, {
+          method: 'POST',
+          path: '/client/sign_ins/signin_123/prepare_first_factor',
+          body: {
+            phoneNumberId: 'phone_123',
+            strategy: 'reset_password_phone_code',
+          },
+        });
+      });
+
+      it('prepares first factor with reset password phone code', async () => {
+        const mockFetch = vi.fn().mockResolvedValue({
+          client: null,
+          response: { id: 'signin_123' },
+        });
+        BaseResource._fetch = mockFetch;
+
+        const signIn = new SignIn({
+          id: 'signin_123',
+          supported_first_factors: [
+            {
+              strategy: 'reset_password_phone_code',
+              phone_number_id: 'phone_123',
+              safe_identifier: '+15551234567',
+            },
+          ],
+        } as any);
+        await signIn.__internal_future.resetPasswordPhoneCode.sendCode();
+
+        expect(mockFetch).toHaveBeenCalledWith({
+          method: 'POST',
+          path: '/client/sign_ins/signin_123/prepare_first_factor',
+          body: {
+            phoneNumberId: 'phone_123',
+            strategy: 'reset_password_phone_code',
+          },
+        });
+      });
+
+      it('throws error when no signIn ID and no phoneNumber', async () => {
+        const signIn = new SignIn();
+
+        await expect(signIn.__internal_future.resetPasswordPhoneCode.sendCode()).rejects.toThrow();
+      });
+
+      it('returns error when reset password phone code factor not found', async () => {
+        const mockFetch = vi.fn().mockResolvedValue({
+          client: null,
+          response: {
+            id: 'signin_123',
+            identifier: '+15551234567',
+            supported_first_factors: [{ strategy: 'password' }],
+          },
+        });
+        BaseResource._fetch = mockFetch;
+
+        const signIn = new SignIn();
+        const result = await signIn.__internal_future.resetPasswordPhoneCode.sendCode({ phoneNumber: '+15551234567' });
+
+        expect(result.error).toBeTruthy();
+        expect(result.error?.code).toBe('factor_not_found');
+      });
+    });
+
+    describe('verifyResetPasswordPhoneCode', () => {
+      afterEach(() => {
+        vi.clearAllMocks();
+      });
+
+      it('attempts first factor with reset password phone code', async () => {
+        const mockFetch = vi.fn().mockResolvedValue({
+          client: null,
+          response: { id: 'signin_123' },
+        });
+        BaseResource._fetch = mockFetch;
+
+        const signIn = new SignIn({ id: 'signin_123' } as any);
+        await signIn.__internal_future.resetPasswordPhoneCode.verifyCode({ code: '123456' });
+
+        expect(mockFetch).toHaveBeenCalledWith({
+          method: 'POST',
+          path: '/client/sign_ins/signin_123/attempt_first_factor',
+          body: {
+            code: '123456',
+            strategy: 'reset_password_phone_code',
+          },
+        });
+      });
+    });
+
     describe('submitResetPassword', () => {
       afterEach(() => {
         vi.clearAllMocks();
diff --git a/packages/react/src/stateProxy.ts b/packages/react/src/stateProxy.ts
@@ -225,6 +225,11 @@ export class StateProxy implements State {
           'verifyCode',
           'submitPassword',
         ] as const),
+        resetPasswordPhoneCode: this.wrapMethods(() => target().resetPasswordPhoneCode, [
+          'sendCode',
+          'verifyCode',
+          'submitPassword',
+        ] as const),
         phoneCode: this.wrapMethods(() => target().phoneCode, ['sendCode', 'verifyCode'] as const),
         mfa: this.wrapMethods(() => target().mfa, [
           'sendPhoneCode',
diff --git a/packages/shared/src/types/signInFuture.ts b/packages/shared/src/types/signInFuture.ts
@@ -138,6 +138,14 @@ export interface SignInFutureResetPasswordSubmitParams {
   signOutOfOtherSessions?: boolean;
 }
 
+export interface SignInFutureResetPasswordPhoneCodeSendParams {
+  /**
+   * The user's phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164). Only supported if
+   * [phone number](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options#phone) is enabled.
+   */
+  phoneNumber?: string;
+}
+
 export type SignInFuturePhoneCodeSendParams = {
   /**
    * The mechanism to use to send the code to the provided phone number. Defaults to `'sms'`.
@@ -168,6 +176,13 @@ export interface SignInFuturePhoneCodeVerifyParams {
   code: string;
 }
 
+export interface SignInFutureResetPasswordPhoneCodeVerifyParams {
+  /**
+   * The one-time code that was sent to the user.
+   */
+  code: string;
+}
+
 export interface SignInFutureSSOParams {
   /**
    * The strategy to use for authentication.
@@ -456,6 +471,26 @@ export interface SignInFutureResource {
     submitPassword: (params: SignInFutureResetPasswordSubmitParams) => Promise<{ error: ClerkError | null }>;
   };
 
+  /**
+   *
+   */
+  resetPasswordPhoneCode: {
+    /**
+     * Used to send a password reset code to the first phone number on the account
+     */
+    sendCode: (params?: SignInFutureResetPasswordPhoneCodeSendParams) => Promise<{ error: ClerkError | null }>;
+
+    /**
+     * Used to verify a password reset code sent via phone. Will cause `signIn.status` to become `'needs_new_password'`.
+     */
+    verifyCode: (params: SignInFutureResetPasswordPhoneCodeVerifyParams) => Promise<{ error: ClerkError | null }>;
+
+    /**
+     * Used to submit a new password, and move the `signIn.status` to `'complete'`.
+     */
+    submitPassword: (params: SignInFutureResetPasswordSubmitParams) => Promise<{ error: ClerkError | null }>;
+  };
+
   /**
    * Used to perform OAuth authentication.
    */
