Example
Build a registration flow
A new person signs up with an email, a password and a display name. The auth service checks the email format and the password policy, refuses an email that is already taken, and stores the new user.
You will build
- The POST /api/v1/register API, connected to the web app
- A users.insert operation next to the lookup
- 2 pieces of logic: the sign-up form and the register logic
- The User registration flow with test data, 4 test cases and 2 requirements, all passing
System map
- Web AppAuth ServicePOST /api/v1/register
- Auth ServiceUsers DBusers.findByIdentifier (query)
- Auth ServiceUsers DBusers.insert (insert)
In a hurry? The free Email & password registration flow in the Store builds all of this for you.Open it in the Store
Part 1: Declare the register API
- 1.
Open Auth Service. On APIs, click Add an API. - 2.
Under Basics: - This endpoint is…
- Provided
- Method
- POST
- Path
- /api/v1/register
- Summary
- Create an account
- Lifecycle
- To do
- 3.
Type the Request body. The ?makes the display name optional.email: string password: string displayName?: string
- 4.
Change the 200 response’s status to 201and type its body:id: integer email: string
- 5.
Click +400 and type its body: error: string field: string
- 6.
Click +409 and type its body, then 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/registerand click Connect 1 API.
Check:
Part 3: Add the insert operation
- 1.
Open Users DB → Resources → Operation. - 2.
Fill in and click Save. Untick may return nothing. - Name
- users.insert
- Type
- insert
- Query / description
- INSERT INTO users (email, password_hash, display_name) VALUES (:email, :passwordHash, :displayName)
- Input fields
- email: string passwordHash: string displayName?: string
- Output fields
- id: integer
Part 4: Build the sign-up form logic on the web app
- 1.
Open Web App → Logic → + Logic. Choose Event / UI action. - Event name
- Submit registration form
- Name
- Submit registration form
- 2.
Inputs: - password
- Text
- displayName
- Text
- 3.
Return values: - success
- Yes / No
- userId
- Whole number
- message
- Text
- 4.
Click Create and open. In Details, make displayName,userIdandmessagenullable (string | null,integer | null) and click the eye next topasswordto lock it. - 5.
Add Make Object (label Build request) with these fields, connected from On Event:email: string password: string displayName?: string
- 6.
Add Call Contract (label Call register) with APIPOST /api/v1/register. Connect the On Event arrow into it andobjectintobody. - 7.
From 201: Return with success= true,message= null,userIdfrom Get Propertyidon the call’sbody. - 8.
From 400 and from 409: a Return each, success= false,userId= null,messagefrom Get Propertyerroronbody. - 9.
From Other: Return with success= false,userId= null,message=Something went wrong. - 10.
Tick Key step on Call registerand the success Return.
Check:
Part 5: Build the register logic on the auth service
- 1.
Open Auth Service → APIs. On POST /api/v1/register, click + Logic. - 2.
Add Break Object with these fields, fed from On Request body:email: string password: string displayName?: string
- 3.
Add Validate Email (field email) onemail, and a BranchEmail valid?on itsvalid. - 4.
From False: Return Response 400. Body: Make Objecterror: string+field: string, witherrorfrom the validationmessageandfield=email. - 5.
From True: Validate Password on password. In Details: Min length8, Require a digit on. Then a BranchPassword strong enough?. - 6.
From its False: Return Response 400, bodyerrorfrom the message,field=password. - 7.
From its True: Query Database users.findByIdentifier(labelFind existing user) withemail. - 8.
From Found: Return Response 409, body Make Objecterror=An account with this email already exists. - 9.
From Not found: Database Insert (label Create user), Operationusers.insert. ConnectemailanddisplayNamefrom Break Object, andpasswordHashfrom a Formathash:{password}. - 10.
Then Return Response 201. Body: Make Objectid: integer+email: string, withidfrom Get Propertyidon the insertresultandemailfrom Break Object. - 11.
Tick Key step on Find existing user,Create userand the 201 answer.
Check:
Part 6: Create the flow
- 1.
Flows → New flow, then Create flow: - Name
- User registration
- Where does the flow start?
- Existing logic
- (the list)
- Web App · Submit registration form (event)
- Criticality
- Important
- 2.
Click the flow’s name → Secret inputs (masked in runs) password, passwordHash→ save.
Check:
Part 7: Add test data
- 1.
Test data → New test data → users.findByIdentifier. NameEmail already registered, WHENemail=="taken@example.com", THEN RETURN:{ "id": 7, "email": "taken@example.com", "passwordHash": "hash:x", "status": "active" } - 2.
Any other email must come back empty. If you built the login, Unknown identifieralready does that. If not, add it: WHENemail= * (any), THEN RETURNnull. - 3.
New test data → users.insert. NameCreated user, WHENemail= * (any), THEN RETURN:{ "id": 2 } - 4.
Expected results → New expected result for User registration.Account created:successequalstrue,userIdexists,messageis null. - 5.
Already registered:successequalsfalse,messagecontains"already exists". - 6.
Invalid email:successequalsfalse,messagecontains"valid email". - 7.
Weak password:successequalsfalse,messagecontains"password must".
Part 8: Write the test cases
- 1.
Open User registration→ Test → Manage… → New, once per row. - 2.
New account: expectAccount created. Under Database & queue expectations, addusers.insert:emailequals"new@example.com"andpasswordHashequals"hash:Secret123".{ "email": "new@example.com", "password": "Secret123", "displayName": "Nia" } - 3.
Email already in use: expectAlready registered.{ "email": "taken@example.com", "password": "Secret123", "displayName": "Nia" } - 4.
Invalid email: expectInvalid email.{ "email": "not-an-email", "password": "Secret123", "displayName": "Nia" } - 5.
Weak password: expectWeak password.{ "email": "new@example.com", "password": "short", "displayName": "Nia" }
Part 9: Link the requirements
- 1.
Requirements → New requirement: An email can only be registered once.FlowUser registration, test caseEmail already in use. - 2.
New requirement: Passwords must meet the password policy.Test caseWeak password.
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:
