Example
Build a login flow
A person types an email and a password in your web app. The auth service looks the user up, checks the password and returns a token. Wrong password and unknown email get the same answer, so nobody can find out which emails have an account.
You will build
- 4 systems on the map, joined by a checked contract
- The POST /api/v1/login API and 2 database or queue operations
- 2 pieces of logic: the form on the web app and the sign-in on the auth service
- The User login flow with test data, 5 test cases and 2 requirements, all passing
System map
- Web AppAuth ServicePOST /api/v1/login
- Auth ServiceUsers DBusers.findByIdentifier (query)
- Auth ServiceEvent Bususer.logged_in (publish)optional
In a hurry? The free Email & password login flow in the Store builds all of this for you.Open it in the Store
Part 1: Create the systems
- 1.
Open Systems in the sidebar and click New system. - 2.
Create the web app, then click Create system. - Name
- Web App
- Type
- Web frontend
- 3.
Click New system again for the auth service. - Name
- Auth Service
- Type
- Backend service
- 4.
And again for the database. - Name
- Users DB
- Type
- Database
- 5.
Optional: a queue for the login event. - Name
- Event Bus
- Type
- Queue / event bus
Skip it if nothing needs to hear about logins. Then skip every step marked optional below.
Check:
Part 2: Declare the login API
- 1.
Open Auth Service. On its APIs tab, click Add an API. - 2.
Under Basics, fill in: - This endpoint is…
- Provided
- Method
- POST
- Path
- /api/v1/login
- Summary
- Sign in with an email and password
- Lifecycle
- To do
- 3.
Under Request, leave Authentication on None and type the Request body: email: string password: string
- 4.
Under Responses, the 200 card is already there. Type its body: accessToken: string refreshToken: string expiresIn: integer tokenType: enum(Bearer)
- 5.
Click +401 to add a second response and type its body: error: string
- 6.
Click Create endpoint.
Part 3: Connect the web app to the API
- 1.
Open Web App and, in its … menu, click Add a dependency…. The Connect systems dialog opens. - 2.
Pick the two sides: - Consumer · depends on the API
- Web App
- Provider · exposes the API
- Auth Service
- 3.
Tick POST /api/v1/loginand click Connect 1 API.
Check:
Part 4: Add the database and queue operations
- 1.
Open Users DB, go to Resources and click Operation. - 2.
Fill in the lookup. Keep may return nothing ticked: that gives the logic its Found and Not found paths. - Name
- users.findByIdentifier
- Type
- query
- Query / description
- SELECT * FROM users WHERE email = :email
- Input fields
- email: string
- Output fields
- id: integer email: string passwordHash: string status: string
- 3.
Click Save. - 4.
Optional: open Event Bus → Resources → Operation, fill in the event and click Save. - Name
- user.logged_in
- Type
- publish
- Input fields
- userId: integer
- Output fields
- (leave empty)
Part 5: Build the form logic on the web app
- 1.
Open Web App → Logic and click + Logic. - 2.
Choose Event / UI action and fill in: - System
- Web App
- Event name
- Submit login form
- Name
- Submit login form
- 3.
Under What it takes, click Add input twice: - password
- Text
- 4.
Under What it gives back, click Add return value three times: - success
- Yes / No
- token
- Text
- message
- Text
- 5.
Click Create and open. The editor opens with an On Event start and a Return step. - 6.
In Details, change the type of tokenandmessagetostring | null, and click the eye next topassword(it turns into a lock) so it is masked in runs. - 7.
Add two Is Required nodes (right-click the canvas, or the Nodes tab). In Details, set Field name to emailon one andpasswordon the other. Connect On Eventemailandpasswordinto theirvalueconnection points. - 8.
Add an AND node. Connect the two validconnection points into itsaandb. - 9.
Add a Branch and label it Inputs valid?. Connect the On Event arrow into it, and the ANDresultintocondition. - 10.
Add a Select node for the error text: conditionfrom the emailvalid,if truefrom the passwordmessage,if falsefrom the emailmessage. - 11.
From Branch False, connect the Return step: success= false,token= null,messagefrom the Selectvalue. - 12.
From Branch True, add Make Object (label it Build request) with these fields, connected from On Event:email: string password: string
- 13.
Add Call Contract and label it Call sign in. In Details, pick API (consumer endpoint)POST /api/v1/login. Connect Branch True into it and the Make Objectobjectintobody. It now has one exit per response: 200, 401 and Other. - 14.
From 200: add a Return with success= true andmessage= null. Add Get Property with pathaccessTokenon the call’sbody, and connect itsvalueintotoken. - 15.
From 401: add a Return with success= false andtoken= null. Add Get Property with patherroron the call’sbody, and connect itsvalueintomessage. - 16.
From Other: add a Return with success= false,token= null andmessage=Something went wrong. - 17.
Right-click Call sign in and the success Return, and tick Key step. Key steps are the steps the flow’s business view shows. - 18.
Click Test in the toolbar, set emailto empty and run it.The False path lights up and the result is success = false with “email is required”.
Check:
Part 6: Build the sign-in logic on the auth service
- 1.
Open Auth Service → APIs. On the POST /api/v1/loginrow, click + Logic (Implement with logic). The editor opens with an On Request start that has abodyconnection point shaped like the request. - 2.
Add Break Object with these fields, and connect On Request bodyinto itsobject:email: string password: string
- 3.
As on the web app: two Is Required ( email,password) → AND → a Branch labelledRequest valid?, with a Select picking the message. - 4.
From False: Return Response with status 401. Its body comes from a Make Object with fielderror: string, filled from the Selectvalue. - 5.
From True: add Query Database and label it Find user. In Details, pick OperationUsers DB · users.findByIdentifier (query). Connect Break Objectemailinto itsemailconnection point. - 6.
Add a Make Object with field error: stringand seterrortoInvalid credentials. Both failure answers below use this one object. - 7.
From Not found: Return Response 401, body from thatInvalid credentialsobject. - 8.
Add Format (label Hash password) with templatehash:{password}, fed from Break Objectpassword. Add Get PropertypasswordHashon the queryresult. Compare the two with Equals.hash: is a stand-in so tests are repeatable. Real code uses bcrypt or argon2. - 9.
From Found: a Branch labelled Validate credentials,conditionfrom Equalsresult. - 10.
From its False: Return Response 401, body from the sameInvalid credentialsobject. - 11.
Add Get Property id(type integer) on the queryresult, then Format (labelCreate token) with templateTOKEN-{id}. - 12.
Add a Make Object for the answer. Connect accessTokenfromCreate tokenand type the rest:refreshToken=REFRESH-TOKEN,expiresIn=3600,tokenType=Bearer.accessToken: string refreshToken: string expiresIn: integer tokenType: enum(Bearer)
- 13.
Optional: from Validate credentials True, add Publish Event with Operation user.logged_in,userIdfrom theidproperty. - 14.
Then (after the publish, or straight from True): Return Response status 200, body from the answer object. - 15.
Tick Key step on Find user,Validate credentialsand the 200 answer.
Check:
Part 7: Create the flow
- 1.
Open Flows in the sidebar and click New flow. - 2.
Fill in, then click Create flow: - Name
- User login
- Where does the flow start?
- Existing logic
- (the list)
- Web App · Submit login form (event)
- Criticality
- Critical
- 3.
In the flow’s bar click its name (the flow’s settings), set Secret inputs (masked in runs) to password, passwordHashand save.
Check:
Part 8: Add test data
- 1.
Open Test data and click New test data. Under Resources, pick users.findByIdentifier. - 2.
Name it Active user. Under WHEN, add a Condition:email=="alex@example.com". Under THEN RETURN, type the value below. Set Secret fields topasswordHash. Click Save.{ "id": 1, "email": "alex@example.com", "passwordHash": "hash:password123", "status": "active" } - 3.
Create one more on users.findByIdentifier: nameUnknown identifier, WHENemail= * (any), THEN RETURNnull. Save.When both match, the more specific one (Active user) wins. - 4.
Open Expected results and click New expected result. Set Checks the output of to User login. - 5.
Name it Login succeeds. Under EXPECT, click Check three times:successequalstrue,tokenexists,messageis null. Save. - 6.
Create Invalid credentials:successequalsfalse,tokenis null,messageequals"Invalid credentials". Save. - 7.
Create Missing field:successequalsfalse,messagecontains"required". Save.
Part 9: Write the test cases
- 1.
Open the User loginflow, press Manage… in its Test panel and click New. For each row below, fill in Name, the Input as an Inline value, Expected response, and click Save test case. - 2.
Valid credentials: expectLogin succeeds.{ "email": "alex@example.com", "password": "password123" } - 3.
Wrong password: expectInvalid credentials.{ "email": "alex@example.com", "password": "wrong-password" } - 4.
Unknown identifier: expectInvalid credentials. Under Test data at each call, pickUnknown identifierfor users.findByIdentifier.{ "email": "nobody@example.com", "password": "password123" } - 5.
Missing identifier: expectMissing field.{ "email": "", "password": "password123" } - 6.
Missing password: expectMissing field.{ "email": "alex@example.com", "password": "" } - 7.
Optional, on Valid credentials: under Step checks, addValidate credentials, connection pointconditionequalstrue. With the event: under Database & queue expectations, adduser.logged_in,userIdequals1.
Part 10: Link the requirements
- 1.
Open Requirements and click New requirement. - 2.
Requirement Reject invalid credentials without revealing whether the account exists.Flows:User login. Test cases that verify it:Wrong passwordandUnknown identifier. Save. - 3.
Requirement The email and password are required to sign in.Test cases:Missing identifierandMissing password. Save.
Check:
Part 11: Run it and verify the code
- 1.
Open the flow, click Test, then Run all. - 2.
A failing test case points at the first step that went wrong. Fix that logic and run again. - 3.
When all pass, open … and pick Check the generated code. It runs the generated code against the same test cases.
Check:
