Two-factor sign-in (code)
FreeFlow@rabbinatix/two-factor-sign-in-code by Rabbinatixupdated Oct 13, 2026
After the password, the person types a six-digit code; wrong codes are counted, and too many lock the sign-in.
The second step of signing in, once the password was right:
- Client app sends the code the person typed with the sign-in challenge, and shows how many tries are left.
- Auth service checks the code has six digits, finds the challenge, refuses an expired or locked one, and compares a hash of the code (codes are never stored as they are). A right code closes the challenge and gives a session.
- User store keeps the challenges. Event bus (optional) receives
user.signed_in_2fa.
Tricky step: a wrong code is counted before the answer goes back, so guessing all million codes is not an option: after the most wrong tries you choose, the person signs in again.
The code itself can come from an authenticator app (TOTP) or a text message; this flow is the same for both.
Previewlanes are roles; you pick your systems when importing
- No matches
FalseNot found400401410Other
Start in Client app. step 1 of 21. key stepOn Enter sign-in code
Call to another system in Client app. step 2 of 21. key stepCall check code
Start in Auth service. step 3 of 21. key stepOn POST /api/v1/two-factor/verify
Resource in Auth service. step 4 of 21. key stepFind the sign-in challenge
Answer in User store. step 5 of 21. key steptwo_factor_challenges.findById
Return in Auth service. step 6 of 21. key stepExpired → 410
Return in Auth service. step 7 of 21. key stepLocked → 429
Step in Auth service. step 8 of 21. key stepRight code?
Resource in Auth service. step 9 of 21. key stepClose the challenge
Answer in User store. step 10 of 21. key steptwo_factor_challenges.complete
Return in Auth service. step 11 of 21. key stepSigned in → 200
Resource in Auth service. step 12 of 21Count a wrong try
Answer in User store. step 13 of 21. key steptwo_factor_challenges.countMiss
Return in Auth service. step 14 of 21. key stepWrong code → 401
Return in Auth service. step 15 of 21. key stepUnknown challenge → 410
Return in Auth service. step 16 of 21. key stepNot a code → 400
Return in Client app. step 17 of 21. key stepReturn
Return in Client app. step 18 of 21. key stepReturn
Return in Client app. step 19 of 21. key stepReturn
Return in Client app. step 20 of 21. key stepReturn
Return in Client app. step 21 of 21. key stepReturn
Client app
Web frontend
Auth service
Backend service
User store
Database
Up and down arrows: previous or next step. Home, End: first or last. Enter: select. Shift F10: more actions.
APIs
POST{base}/two-factor/verify· Check a sign-in code
Auth service provides it · Client app calls it
Request body
challengeId: string code: string
200
accessToken: string
400
error: string
401
error: string triesLeft: integer
410
error: string
429
error: string
Data operations
two_factor_challenges.findByIdqueryon User store(challengeId: string)
two_factor_challenges.countMissupdateon User store(challengeId: string)
two_factor_challenges.completeupdateon User store(challengeId: string)
Test cases
Right code signs in→ Signed in
Wrong code is counted→ Wrong code, 4 tries left
Last wrong try→ Wrong code, none left
Locked after too many wrong tries, even with the right code→ Locked
Code typed too late→ Expired
Not six digits→ Not six digits
Signing in publishes user.signed_in_2fa→ Signed inwith “Publish user.signed_in_2fa”
Requirements
Every wrong code is counted, and the person is told how many tries are left.
After the most wrong tries, even the right code no longer works.
A code works only for a short time.
Roles (4)
Client app
Where the person types the code · Web frontend or mobile app
Auth service
Checks the code and gives the session · Backend service
User store
Database with the sign-in challenges · Database
Event bus (optional)
Receives user.signed_in_2fa (optional) · Queue / event bus
Settings
Most wrong tries5
Publish user.signed_in_2faoff
Code fieldcode (renamable)
Also as a whiteboard
Fits these system maps
Versions
