QA sessions
Give every tester their own sandbox on one shared proxy URL. Claim identity for mocks, watch all traffic by default, and keep staging fully collision-free.
On this page
Shared staging is a roulette wheel. You mock the cart as empty; someone else's test suddenly sees an empty cart too. FlowMock fixes this with sessions - isolated override scopes on a single proxy URL.
The session key
A session is identified by a session key - any string your team agrees on:
qa-alicefor manual testingqa-bobfor another testerci-run-4821for a CI pipeline
Send it on every proxied request:
x-flowmock-session: qa-aliceFlowMock normalizes the key (trims whitespace, strips newlines, caps at 200 characters) and matches sessions by exact string equality.
What a session controls
Each session has its own:
- Active scenario - a bundle of mocks you switch between
- Individual mock activations - one-off overrides on top of the scenario
- Global delay - simulate slow responses for the whole session
- Label - a human-readable note ("Testing expired token flow")
Change Alice's session and Bob's session stays untouched.
How the proxy finds your session
The x-flowmock-session header is the simplest and most reliable method. FlowMock also supports:
- JWT claims in
Authorization(configured per environment) - Raw headers, cookies, or query parameters
- Session cookies from your app
Configure session detection in your environment settings. For most teams, the explicit header is the way to go - especially for CI.
Sessions in the dashboard
The session strip at the top of the environment is where identity lives. Traffic (the live log feed) is separate - see Traffic.
Claim: which session is you
When sessions appear from real traffic, FlowMock asks Which of these is you? Pick your pill. That claim is what mocks, scenarios, and delays apply to.
Claiming is for identity, not for permission to see logs. Traffic already shows every session's requests by default.
Watch all vs focus on one
| Mode | How you get there | What Traffic shows |
|---|---|---|
| All sessions (default) | Land on Traffic, or choose All sessions in the picker | Everyone's requests, with avatars + Sessions filter |
| Focused (You) | Claim yourself, or Return to my session | Only your requests - no avatars, no Sessions filter |
| View as | Pick a teammate in the session picker | Their requests, read-only - your overrides stay hidden |
While watching all, your claimed identity still applies: flip mocks for yourself without leaving the team-wide feed.
View as a teammate
Step into another session to see their reality (active scenario, what mocks they would hit). You cannot edit their overrides from view-as - return to your session when you are done.
Sessions in CI
Automate session setup with the Public API. A typical flow:
PUT /api/v1/sessions/ci-42with your desired scenario- Run tests with
x-flowmock-session: ci-42 DELETE /api/v1/sessions/ci-42?mode=deletewhen done
See Sessions API for the full reference.
Common questions
Can two people share a session key? Yes, but they'll see the same mocks. Usually you want one key per person or CI run.
What happens if I forget the header? FlowMock falls back to other detection methods or an anonymous default session. Your mocks might not apply - always send the header in CI.
Do sessions expire? Sessions stay active as long as traffic keeps coming. Idle sessions are cleaned up over time but can be recreated on the next request.
Do I have to pick a session to see logs? No. Open Traffic and the feed is live for all sessions. Pick your session when you want mocks to apply to you.