Skip to content

docs: Document requires_totp_mfa JWT claim #1281

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
promptless wants to merge 7 commits into
base: dev
Choose a base branch
from
+1 −0
Open

docs: Document requires_totp_mfa JWT claim #1281

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
3af68cc
Document requires_totp_mfa JWT claim
promptless[bot] Mar 23, 2026
b094812
Merge branch 'dev' into promptless/document-requires-totp-mfa-jwt-claim
promptless[bot] Apr 17, 2026
c2e0383
Merge branch 'dev' into promptless/document-requires-totp-mfa-jwt-claim
promptless[bot] Apr 17, 2026
0590fb3
Merge branch 'dev' into promptless/document-requires-totp-mfa-jwt-claim
promptless[bot] Apr 17, 2026
5919d21
Merge branch 'dev' into promptless/document-requires-totp-mfa-jwt-claim
promptless[bot] Apr 18, 2026
0818d01
Merge branch 'dev' into promptless/document-requires-totp-mfa-jwt-claim
promptless[bot] Apr 18, 2026
9f87333
Merge branch 'dev' into promptless/document-requires-totp-mfa-jwt-claim
promptless[bot] Apr 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/content/docs/(guides)/concepts/jwt.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ Stack Auth JWTs contain standardized headers and claims that power authenticatio
- **`project_id`**: Your Stack Auth project ID
- **`branch_id`**: The project branch (currently always `main`)
- **`refresh_token_id`**: ID of the associated refresh token
- **`requires_totp_mfa`**: Whether the user has TOTP multi-factor authentication enabled
Copy link
Copy Markdown
Contributor Author

@promptless promptless bot Mar 23, 2026

Choose a reason for hiding this comment

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

Citation: Based on commit c8b5168 "Add requires_totp_mfa to JWT". The commit added requires_totp_mfa to tokens.tsx, schema-fields.ts, and the example JWT in jwt.mdx, but didn't add a description in the Stack Auth Specific Claims section. The field indicates whether the user has TOTP MFA enabled, as shown in the e2e tests in access-token-refresh.test.ts.
View source

Copy link
Copy Markdown
Contributor

@greptile-apps greptile-apps bot Mar 23, 2026

Choose a reason for hiding this comment

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

P2 Description diverges from internal OpenAPI spec

The added description says "Whether the user has TOTP multi-factor authentication enabled," but the internal OpenAPI spec in packages/stack-shared/src/interface/crud/users.ts describes this field as "Whether the user is required to use TOTP MFA to sign in". These are subtly different: a user could have TOTP configured without it being required at sign-in, or an admin could enforce MFA on users who already have TOTP set up. The claim name itself (requires_totp_mfa) and its SDK mapping to isMultiFactorRequired both reinforce the "required to use" semantics rather than simply "has enabled."

Consider aligning the docs with the existing internal description:

Suggested change
- **`requires_totp_mfa`**: Whether the user has TOTP multi-factor authentication enabled
- **`requires_totp_mfa`**: Whether the user is required to use TOTP MFA to sign in

- **`role`**: Always set to `authenticated` for valid users
- **`name`**: The user's display name (nullable)
- **`email`**: The user's primary email address (nullable)
Expand Down
Loading