Skip to content

Conversation

@octoper
Copy link
Member

@octoper octoper commented Jan 30, 2026

🔎 Previews:

What does this solve?

This PR adds documentation for the new setup-mfa session task feature, which allows applications to require all users to set up multi-factor authentication after signing in or signing up. This simplifies the MFA enforcement flow by using Clerk's session task system instead of requiring developers to write custom middleware.

What changed?

clerk/javascript#7626

New Documentation:

  • Created comprehensive component reference for <TaskSetupMfa /> with examples for Next.js, React, React Router, TanStack React Start, and JavaScript SDK
    • Created a task-properties partial to be used across the Task components for their # Properties sections
  • Added setup-mfa task to the session tasks table and guides

Updated Documentation:

  • Updated the Multi-factor authenticator section in /auth-strategies/sign-up-sign-in-options to be the source of truth for setting up MFA and enabling the Require setting.
    • Deleted the /force-mfa guide in favor of this section
  • Updated session tasks documentation:
    • Adds the new setup-mfa task
    • Adds searchable keywords for each of the session tasks
  • Updated custom flows guide to reference MFA setup flows for the setup-mfa task
    • Consolidated the /manage-sms-based-mfa and /manage-totp-based-mfa guides. Now it's just the /manage-mfa guide. This creates a single source of truth for a custom flow for managing MFA.
      ensured the flows handle completing a user's setup-mfa task
  • Added manifest entry for the new component documentation

@octoper octoper requested a review from a team as a code owner January 30, 2026 13:35
@vercel
Copy link

vercel bot commented Jan 30, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
clerk-docs Ready Ready Preview Feb 9, 2026 8:03pm

Request Review

- Introduced a new guide for building a custom flow for the setup MFA session task.
- Updated links in the session tasks table and MFA requirement documentation to point to the new guide.
- Made minor formatting adjustments in various documentation files for clarity.
@octoper octoper force-pushed the vaggelis/introduce-setup-mfa-session-task branch from 2bcab1d to f5f8475 Compare February 2, 2026 16:35
@octoper octoper marked this pull request as ready for review February 2, 2026 16:35
@octoper octoper added the Blocked label Feb 2, 2026
@alexisintech alexisintech changed the title Intorduces <TaskSetupMfa /> component and the setup-mfa session task Introduces <TaskSetupMfa /> component and the setup-mfa session task Feb 3, 2026
@alexisintech
Copy link
Member

alexisintech commented Feb 3, 2026

I've posted my docs review!

  • updated the Multi-factor authenticator section in /auth-strategies/sign-up-sign-in-options to be the source of truth for setting up MFA and enabling the Require setting.
    • deleted the /force-mfa guide in favor of this section
  • updated the session tasks guide to have searchable keywords for each of the session tasks
  • consolidated the /manage-sms-based-mfa and /manage-totp-based-mfa guides
    • now it just the /manage-mfa guide
    • this creates a single source of truth for a custom flow for managing MFA
    • ensured the flows handle completing a user's setup-mfa task
      Screenshot 2026-02-03 at 17 44 48
    • added that the authentication checks don't block "signed-out" users from the pages
      Screenshot 2026-02-03 at 17 44 56
    • tested the nextjs examples, they're working great. just need to test expo once chris has updated the expo sdk to a working state. the expo examples are the nextjs examples, just translated to react native, but i still want to test them!
    • deleted the /setup-mfa-session-task guide in favor of this /manage-mfa guide
  • added necessary redirects for the deleted files

TODO:

  • Alexis: test expo examples once chris has updated the expo sdk to a working state (but this is nonblocking. i plan to test all of expo examples in the core 3 branch, so its fine to merge this into the core 3 branch)

@alexisintech
Copy link
Member

@SarahSoutoul @manovotny I've finished my docs review, could I get more eyes on this before we merge into core 3 branch :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if it's an issue or not, but all of our other images for components are png.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@octoper could you re-export from figma or wherever you got it as a png instead of jpg? just for the sake of consistency in our images

@SarahSoutoul
Copy link
Contributor

@SarahSoutoul @manovotny I've finished my docs review, could I get more eyes on this before we merge into core 3 branch :)

Have left a very minor docs review, and some comments/ discussion pts! @alexisintech

- The layout page that checks if the user is signed in
- The page where users can manage their account, including their MFA settings
- The page where users can add TOTP MFA
- The layout page that checks if the user is signed in.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a list - these fragment sentences don't finish any sentence so they don't get full stops

Copy link
Contributor

@SarahSoutoul SarahSoutoul Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair. I only added them cause they were on the other fragments of that page for consistency.

@alexisintech
Copy link
Member

@SarahSoutoul replied and addressed everything, think this is now just waiting on vaggelis to update the image :) thanks for the review!

@alexisintech
Copy link
Member

update on getting the image updated:

Screenshot 2026-02-04 at 16 07 04

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants