Think of FlowMock as a smart middleman. Your app sends requests to FlowMock. FlowMock either returns a mock response or forwards the request to your real staging API and passes the response back.

text

Your app  →  FlowMock proxy  →  Staging API
                ↓
           Mock? Return it.
           No mock? Forward.

That's the whole trick. No backend deploys. No database surgery. No asking DevOps for a favor.

The pieces

Piece	What it is	Plain English
Project	A container for one staging API	"Our checkout backend"
Environment	A proxy endpoint with its own URL	"Staging" or "QA"
Session	An isolated override scope	"Alice's sandbox"
Mock	A response override for a route	"Return 402 for POST /pay"
Transform	A body patch after mock or upstream	"Mark every task done"
Scenario	A bundle of mocks you switch between	"Payment declined" preset

Two shortcuts that matter in practice: Record scenario builds a scenario from a real click-through (see Scenarios), and AI edit rewrites a captured response body from plain English (see Traffic).

Request lifecycle

When a request hits the proxy:

Resolve the session - from x-flowmock-session, a JWT claim, a cookie, or other configured source
Check for mocks - match the request path, method, query params, and body against active overrides
Apply or pass through - if a mock matches, return it; otherwise forward to staging
Run matching transforms - stack body patches (global → scenario → session) on the response
Log everything - record the request and response for the dashboard (and your peace of mind)

Mocks are evaluated per session. Your "out of stock" mock doesn't leak to anyone else's session. Transforms patch bodies without replacing status or headers.

Live updates

When you change something in the dashboard - activate a mock, switch a scenario, update session state - the proxy picks it up right away. No restarts. Flip a scenario, refresh your app, done.

One URL for the whole team

Everyone on QA uses the same proxy URL. Isolation comes from session keys, not separate environments.

Alice sends x-flowmock-session: qa-alice
Bob sends x-flowmock-session: qa-bob
CI sends x-flowmock-session: ci-run-4821

Same URL. Different worlds.

When mocks don't apply

If no mock matches, the request goes to staging exactly as if FlowMock weren't there. Headers, cookies, auth tokens - all forwarded. That's intentional. FlowMock enhances staging; it doesn't replace it.

QA sessions - how session keys work in detail
Traffic - live feed across all sessions
Mocks and overrides - creating and matching mocks
Transforms - patch live response bodies after mock or upstream
Cookie auth - when your app uses cookie-based sessions