RabbinatixDocs
Sign inGet started

Example

Build a password reset flow

A person who forgot their password types their email. The auth service looks the user up and, if there is one, sends a reset event for the mail service to pick up. Known and unknown emails get the same answer, so nobody can find out which emails have an account.

You will build

  • The POST /api/v1/password-reset API, connected to the web app
  • A password_reset.requested event on the event bus
  • 2 pieces of logic: the reset form and the reset logic
  • The Password reset flow with test data, 3 test cases and 1 requirement, all passing

System map

  • Web AppAuth ServicePOST /api/v1/password-reset
  • Auth ServiceUsers DBusers.findByIdentifier (query)
  • Auth ServiceEvent Buspassword_reset.requested (publish)

This guide reuses Web App, Auth Service, Users DB, Event Bus and users.findByIdentifier from the login example, and its Active user and Unknown identifier test data. Starting fresh? Do the login steps 1, 4 and 8 first.

Part 1: Declare the reset API

  1. 1.

    Open Auth Service. On APIs, click Add an API.

  2. 2.

    Under Basics:

    This endpoint is…
    Provided
    Method
    POST
    Path
    /api/v1/password-reset
    Summary
    Send a password reset link
    Lifecycle
    To do
  3. 3.

    Type the Request body:

    email: string
  4. 4.

    Change the 200 response’s status to 202 and type its body:

    message: string
  5. 5.

    Click +400, type its body and click Create endpoint.

    error: string

Part 2: Connect the web app to the API

  1. 1.

    Open Web App → … → Add a dependency…. Consumer Web App, provider Auth Service.

  2. 2.

    Tick POST /api/v1/password-reset and click Connect 1 API.

Check: The Web App → Auth Service line stays green and carries one more API.

Part 3: Add the reset event

  1. 1.

    Open Event Bus → Resources → Operation.

  2. 2.

    Fill in and click Save.

    Name
    password_reset.requested
    Type
    publish
    Input fields
    userId: integer
    Output fields
    (leave empty)

    The mail service that sends the link listens to this event. It is not part of this flow.

Part 4: Build the reset form logic on the web app

  1. 1.

    Open Web App → Logic → + Logic. Choose Event / UI action.

    Event name
    Submit reset form
    Name
    Submit reset form
  2. 2.

    Inputs:

    email
    Email
  3. 3.

    Return values:

    success
    Yes / No
    message
    Text
  4. 4.

    Click Create and open.

  5. 5.

    Add Make Object (label Build request) with the field below, connected from On Event email:

    email: string
  6. 6.

    Add Call Contract (label Ask for a reset) with API POST /api/v1/password-reset. Connect the On Event arrow into it and object into body.

  7. 7.

    From 202: Return with success = true and message from Get Property message on the call’s body.

  8. 8.

    From 400: Return with success = false and message from Get Property error on body.

  9. 9.

    From Other: Return with success = false and message = Something went wrong.

  10. 10.

    Tick Key step on Ask for a reset.

Check: The Problems tab is empty.

Part 5: Build the reset logic on the auth service

  1. 1.

    Open Auth Service → APIs. On POST /api/v1/password-reset, click + Logic.

  2. 2.

    Add Break Object with the field below, fed from On Request body:

    email: string
  3. 3.

    Add Validate Email on email (set Field name to email), and a Branch Email valid? on its valid.

  4. 4.

    From False: Return Response 400. Body: Make Object error: string, with error from the validation message.

  5. 5.

    From True: Query Database users.findByIdentifier (label Find user), with email from Break Object.

  6. 6.

    Add one Make Object for the answer, field message: string, set to If the account exists, we sent a reset link. Both answers below use it.

  7. 7.

    From Found: Publish Event (label Ask for the email), Operation password_reset.requested, with userId from Get Property id on the query result. Then Return Response 202 with the answer object.

  8. 8.

    From Not found: Return Response 202 with the same answer object.

    Same status, same words: the answer never tells whether the email has an account.

  9. 9.

    Tick Key step on Find user, Ask for the email and both 202 answers.

Check: The Problems tab is empty.

Part 6: Create the flow

  1. 1.

    Flows → New flow, then Create flow:

    Name
    Password reset
    Where does the flow start?
    Existing logic
    (the list)
    Web App · Submit reset form (event)
    Criticality
    Important

Check: The flow has lanes for Web App, Auth Service, Users DB and Event Bus, drawn from the logic.

Part 7: Add test data

  1. 1.

    For users.findByIdentifier, the login’s Active user (alex@example.com) and Unknown identifier (any other email) already answer. Nothing to add there.

  2. 2.

    Expected results → New expected result for Password reset. Reset link sent: success equals true, message contains "reset link".

  3. 3.

    Reset refused: success equals false, message contains "valid email".

Part 8: Write the test cases

  1. 1.

    Open Password reset → Test → Manage… → New, once per row.

  2. 2.

    Known email: expect Reset link sent. Under Database & queue expectations, add password_reset.requested: userId equals 1.

    { "email": "alex@example.com" }
  3. 3.

    Unknown email: expect Reset link sent. Under Test data at each call, pick Unknown identifier for users.findByIdentifier.

    { "email": "nobody@example.com" }
  4. 4.

    Not an email: expect Reset refused.

    { "email": "alex-at-example" }

Part 9: Link the requirement

  1. 1.

    Requirements → New requirement: The reset answer never reveals whether an email has an account. Flow Password reset, test cases Known email and Unknown email.

Part 10: Run it and verify the code

  1. 1.

    Open the flow → Test → Run all. Fix any failing step and run again.

  2. 2.

    Open … and pick Check the generated code.

Check: Every test case is green, and the requirement reads Verified (passing).