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)
Part 1: Declare the reset API
- 1.
Open Auth Service. On APIs, click Add an API. - 2.
Under Basics: - This endpoint is…
- Provided
- Method
- POST
- Path
- /api/v1/password-reset
- Summary
- Send a password reset link
- Lifecycle
- To do
- 3.
Type the Request body: email: string
- 4.
Change the 200 response’s status to 202and type its body:message: string
- 5.
Click +400, type its body and click Create endpoint. error: string
Part 2: Connect the web app to the API
- 1.
Open Web App → … → Add a dependency…. Consumer Web App, providerAuth Service. - 2.
Tick POST /api/v1/password-resetand click Connect 1 API.
Check:
Part 3: Add the reset event
- 1.
Open Event Bus → Resources → Operation. - 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.
Open Web App → Logic → + Logic. Choose Event / UI action. - Event name
- Submit reset form
- Name
- Submit reset form
- 2.
Inputs: - 3.
Return values: - success
- Yes / No
- message
- Text
- 4.
Click Create and open. - 5.
Add Make Object (label Build request) with the field below, connected from On Eventemail:email: string
- 6.
Add Call Contract (label Ask for a reset) with APIPOST /api/v1/password-reset. Connect the On Event arrow into it andobjectintobody. - 7.
From 202: Return with success= true andmessagefrom Get Propertymessageon the call’sbody. - 8.
From 400: Return with success= false andmessagefrom Get Propertyerroronbody. - 9.
From Other: Return with success= false andmessage=Something went wrong. - 10.
Tick Key step on Ask for a reset.
Check:
Part 5: Build the reset logic on the auth service
- 1.
Open Auth Service → APIs. On POST /api/v1/password-reset, click + Logic. - 2.
Add Break Object with the field below, fed from On Request body:email: string
- 3.
Add Validate Email on email(set Field name toemail), and a BranchEmail valid?on itsvalid. - 4.
From False: Return Response 400. Body: Make Objecterror: string, witherrorfrom the validationmessage. - 5.
From True: Query Database users.findByIdentifier(labelFind user), withemailfrom Break Object. - 6.
Add one Make Object for the answer, field message: string, set toIf the account exists, we sent a reset link.Both answers below use it. - 7.
From Found: Publish Event (label Ask for the email), Operationpassword_reset.requested, withuserIdfrom Get Propertyidon the queryresult. Then Return Response202with the answer object. - 8.
From Not found: Return Response 202with the same answer object.Same status, same words: the answer never tells whether the email has an account. - 9.
Tick Key step on Find user,Ask for the emailand both 202 answers.
Check:
Part 6: Create the flow
- 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:
Part 7: Add test data
- 1.
For users.findByIdentifier, the login’sActive user(alex@example.com) andUnknown identifier(any other email) already answer. Nothing to add there. - 2.
Expected results → New expected result for Password reset.Reset link sent:successequalstrue,messagecontains"reset link". - 3.
Reset refused:successequalsfalse,messagecontains"valid email".
Part 8: Write the test cases
- 1.
Open Password reset→ Test → Manage… → New, once per row. - 2.
Known email: expectReset link sent. Under Database & queue expectations, addpassword_reset.requested:userIdequals1.{ "email": "alex@example.com" } - 3.
Unknown email: expectReset link sent. Under Test data at each call, pickUnknown identifierfor users.findByIdentifier.{ "email": "nobody@example.com" } - 4.
Not an email: expectReset refused.{ "email": "alex-at-example" }
Part 9: Link the requirement
- 1.
Requirements → New requirement: The reset answer never reveals whether an email has an account.FlowPassword reset, test casesKnown emailandUnknown email.
Part 10: Run it and verify the code
- 1.
Open the flow → Test → Run all. Fix any failing step and run again. - 2.
Open … and pick Check the generated code.
Check:
