RabbinatixDocs
Sign inGet started

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. 1.

    Open Systems in the sidebar and click New system.

  2. 2.

    Create the web app, then click Create system.

    Name
    Web App
    Type
    Web frontend
  3. 3.

    Click New system again for the auth service.

    Name
    Auth Service
    Type
    Backend service
  4. 4.

    And again for the database.

    Name
    Users DB
    Type
    Database
  5. 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: The map shows your systems with no lines between them yet.

Part 2: Declare the login API

The API is the contract: what the web app sends and what the auth service answers.

  1. 1.

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

  2. 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. 3.

    Under Request, leave Authentication on None and type the Request body:

    email: string
    password: string
  4. 4.

    Under Responses, the 200 card is already there. Type its body:

    accessToken: string
    refreshToken: string
    expiresIn: integer
    tokenType: enum(Bearer)
  5. 5.

    Click +401 to add a second response and type its body:

    error: string
  6. 6.

    Click Create endpoint.

Part 3: Connect the web app to the API

  1. 1.

    Open Web App and, in its … menu, click Add a dependency…. The Connect systems dialog opens.

  2. 2.

    Pick the two sides:

    Consumer · depends on the API
    Web App
    Provider · exposes the API
    Auth Service
  3. 3.

    Tick POST /api/v1/login and click Connect 1 API.

Check: On the map, a green line joins Web App to Auth Service. Green means both sides agree on every field.

Part 4: Add the database and queue operations

Operations are what logic can ask a database or a queue to do. They live on the system’s Resources tab.

  1. 1.

    Open Users DB, go to Resources and click Operation.

  2. 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. 3.

    Click Save.

  4. 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

What the web app does when the person presses Sign in: check the form, call the API, turn the answer into something the screen can show.

  1. 1.

    Open Web App → Logic and click + Logic.

  2. 2.

    Choose Event / UI action and fill in:

    System
    Web App
    Event name
    Submit login form
    Name
    Submit login form
  3. 3.

    Under What it takes, click Add input twice:

    email
    Email
    password
    Text
  4. 4.

    Under What it gives back, click Add return value three times:

    success
    Yes / No
    token
    Text
    message
    Text
  5. 5.

    Click Create and open. The editor opens with an On Event start and a Return step.

  6. 6.

    In Details, change the type of token and message to string | null, and click the eye next to password (it turns into a lock) so it is masked in runs.

  7. 7.

    Add two Is Required nodes (right-click the canvas, or the Nodes tab). In Details, set Field name to email on one and password on the other. Connect On Event email and password into their value connection points.

  8. 8.

    Add an AND node. Connect the two valid connection points into its a and b.

  9. 9.

    Add a Branch and label it Inputs valid?. Connect the On Event arrow into it, and the AND result into condition.

  10. 10.

    Add a Select node for the error text: condition from the email valid, if true from the password message, if false from the email message.

  11. 11.

    From Branch False, connect the Return step: success = false, token = null, message from the Select value.

  12. 12.

    From Branch True, add Make Object (label it Build request) with these fields, connected from On Event:

    email: string
    password: string
  13. 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 Object object into body. It now has one exit per response: 200, 401 and Other.

  14. 14.

    From 200: add a Return with success = true and message = null. Add Get Property with path accessToken on the call’s body, and connect its value into token.

  15. 15.

    From 401: add a Return with success = false and token = null. Add Get Property with path error on the call’s body, and connect its value into message.

  16. 16.

    From Other: add a Return with success = false, token = null and message = Something went wrong.

  17. 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. 18.

    Click Test in the toolbar, set email to empty and run it.

    The False path lights up and the result is success = false with “email is required”.

Check: The Problems tab is empty.

Part 6: Build the sign-in logic on the auth service

What the auth service does when the login API is called.

  1. 1.

    Open Auth Service → APIs. On the POST /api/v1/login row, click + Logic (Implement with logic). The editor opens with an On Request start that has a body connection point shaped like the request.

  2. 2.

    Add Break Object with these fields, and connect On Request body into its object:

    email: string
    password: string
  3. 3.

    As on the web app: two Is Required (email, password) → AND → a Branch labelled Request valid?, with a Select picking the message.

  4. 4.

    From False: Return Response with status 401. Its body comes from a Make Object with field error: string, filled from the Select value.

  5. 5.

    From True: add Query Database and label it Find user. In Details, pick Operation Users DB · users.findByIdentifier (query). Connect Break Object email into its email connection point.

  6. 6.

    Add a Make Object with field error: string and set error to Invalid credentials. Both failure answers below use this one object.

  7. 7.

    From Not found: Return Response 401, body from that Invalid credentials object.

  8. 8.

    Add Format (label Hash password) with template hash:{password}, fed from Break Object password. Add Get Property passwordHash on the query result. Compare the two with Equals.

    hash: is a stand-in so tests are repeatable. Real code uses bcrypt or argon2.

  9. 9.

    From Found: a Branch labelled Validate credentials, condition from Equals result.

  10. 10.

    From its False: Return Response 401, body from the same Invalid credentials object.

  11. 11.

    Add Get Property id (type integer) on the query result, then Format (label Create token) with template TOKEN-{id}.

  12. 12.

    Add a Make Object for the answer. Connect accessToken from Create token and type the rest: refreshToken = REFRESH-TOKEN, expiresIn = 3600, tokenType = Bearer.

    accessToken: string
    refreshToken: string
    expiresIn: integer
    tokenType: enum(Bearer)
  13. 13.

    Optional: from Validate credentials True, add Publish Event with Operation user.logged_in, userId from the id property.

  14. 14.

    Then (after the publish, or straight from True): Return Response status 200, body from the answer object.

  15. 15.

    Tick Key step on Find user, Validate credentials and the 200 answer.

Check: The Problems tab is empty, and the Text steps tab reads like the rules above.

Part 7: Create the flow

  1. 1.

    Open Flows in the sidebar and click New flow.

  2. 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. 3.

    In the flow’s bar click its name (the flow’s settings), set Secret inputs (masked in runs) to password, passwordHash and save.

Check: The flow shows lanes Web App → Auth Service → Users DB → Auth Service → Web App, drawn from the logic. You drew nothing.

Part 8: Add test data

Test data answers for the database while the flow runs. Expected results say what the right result looks like.

  1. 1.

    Open Test data and click New test data. Under Resources, pick users.findByIdentifier.

  2. 2.

    Name it Active user. Under WHEN, add a Condition: email == "alex@example.com". Under THEN RETURN, type the value below. Set Secret fields to passwordHash. Click Save.

    { "id": 1, "email": "alex@example.com", "passwordHash": "hash:password123", "status": "active" }
  3. 3.

    Create one more on users.findByIdentifier: name Unknown identifier, WHEN email = * (any), THEN RETURN null. Save.

    When both match, the more specific one (Active user) wins.

  4. 4.

    Open Expected results and click New expected result. Set Checks the output of to User login.

  5. 5.

    Name it Login succeeds. Under EXPECT, click Check three times: success equals true, token exists, message is null. Save.

  6. 6.

    Create Invalid credentials: success equals false, token is null, message equals "Invalid credentials". Save.

  7. 7.

    Create Missing field: success equals false, message contains "required". Save.

Part 9: Write the test cases

A test case is one test: an input, the test data to use, and the result you expect.

  1. 1.

    Open the User login flow, 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. 2.

    Valid credentials: expect Login succeeds.

    { "email": "alex@example.com", "password": "password123" }
  3. 3.

    Wrong password: expect Invalid credentials.

    { "email": "alex@example.com", "password": "wrong-password" }
  4. 4.

    Unknown identifier: expect Invalid credentials. Under Test data at each call, pick Unknown identifier for users.findByIdentifier.

    { "email": "nobody@example.com", "password": "password123" }
  5. 5.

    Missing identifier: expect Missing field.

    { "email": "", "password": "password123" }
  6. 6.

    Missing password: expect Missing field.

    { "email": "alex@example.com", "password": "" }
  7. 7.

    Optional, on Valid credentials: under Step checks, add Validate credentials, connection point condition equals true. With the event: under Database & queue expectations, add user.logged_in, userId equals 1.

Part 10: Link the requirements

  1. 1.

    Open Requirements and click New requirement.

  2. 2.

    Requirement Reject invalid credentials without revealing whether the account exists. Flows: User login. Test cases that verify it: Wrong password and Unknown identifier. Save.

  3. 3.

    Requirement The email and password are required to sign in. Test cases: Missing identifier and Missing password. Save.

Check: Both requirements show under Coverage.

Part 11: Run it and verify the code

  1. 1.

    Open the flow, click Test, then Run all.

  2. 2.

    A failing test case points at the first step that went wrong. Fix that logic and run again.

  3. 3.

    When all pass, open … and pick Check the generated code. It runs the generated code against the same test cases.

Check: Every test case is green, and both requirements read Verified (passing).