FlowMock

How it works

One proxy URL, one real staging API, isolated sessions — here's the mental model.

On this page

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

PieceWhat it isPlain English
ProjectA container for one staging API"Our checkout backend"
EnvironmentA proxy endpoint with its own URL"Staging" or "QA"
SessionAn isolated override scope"Alice's sandbox"
MockA response override for a route"Return 402 for POST /pay"
ScenarioA bundle of mocks you switch between"Payment declined" preset

Request lifecycle

When a request hits the proxy:

  1. Resolve the session — from x-flowmock-session, a JWT claim, a cookie, or other configured source
  2. Check for mocks — match the request path, method, query params, and body against active overrides
  3. Apply or pass through — if a mock matches, return it; otherwise forward to staging
  4. 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.

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.