FlowMock
Log inStart free

Cookie auth

Route cookie-based sessions through FlowMock without losing login state.

On this page

Lots of apps authenticate with cookies - Set-Cookie on login, browser sends them back automatically. That works great until you put a proxy in the middle.

FlowMock can forward cookies to staging and pass Set-Cookie responses back to your app. But there's a catch with custom domains: cookies are picky about which domain they're set for.

The problem

When your app talks directly to staging-api.yourcompany.com, cookies are scoped to that domain. Point your app at a FlowMock proxy URL (p.flowmock.dev or a custom domain), and cookie domains might not line up.

Symptoms:

  • Login works on staging, breaks through the proxy
  • Session cookies aren't sent on subsequent requests
  • Set-Cookie responses get ignored by the browser

The fix: custom domain + CNAME

The reliable setup is a custom domain for your FlowMock proxy:

  1. Add a domain in FlowMock (e.g. api-qa.yourcompany.com)
  2. Create a CNAME record pointing to FlowMock's target
  3. Verify the domain in dashboard settings
  4. Point your app at https://api-qa.yourcompany.com instead of the default proxy URL

Now cookies can be scoped to a subdomain of your real domain. The browser treats it like talking to your own infrastructure.

When your API is on a subdomain (e.g. mock-api.yourcompany.com) but your frontend is on the apex (yourcompany.com) or another subdomain, FlowMock rewrites Set-Cookie responses to use your registrable root domain (e.g. Domain=yourcompany.com) so the session cookie is shared across subdomains.

Using the browser extension instead

If you test in Chrome or Firefox with the browser extension, your app keeps calling its real API URL and the extension routes those calls through FlowMock. With Forward site cookies on (the default, under the site's Advanced settings on the Connect page), the extension adds the cookies your browser already holds for your API to each routed request, so a session you're signed in to keeps working without a custom domain.

A login that sets new cookies through the proxy still follows the browser's rules: the cookies land on the proxy host, not your API. Sign in with FlowMock off for the site, then turn it back on - or set up the custom domain above.

What FlowMock forwards

By default, FlowMock forwards:

  • Request cookies - sent by the browser to staging
  • Response Set-Cookie - passed back to your app
  • Auth headers - Authorization, custom tokens, etc.

No stripping, no rewriting - unless you've configured redaction rules.

SameSite and Secure

Modern browsers enforce SameSite and Secure cookie attributes. If your staging cookies use SameSite=Strict, cross-site requests might not include them.

Through a custom domain on your own subdomain, cookies behave like same-site requests. That's why the CNAME setup matters.

Framework notes

Most auth libraries scope the session cookie to the host that issued it. When your frontend talks to the FlowMock proxy on a custom domain, the library has to be told that the cookie is shared across your subdomains, and that the proxy host is a trusted caller.

Better Auth

Enable cross-subdomain cookies and add the proxy host to trustedOrigins:

ts
import { betterAuth } from "better-auth";

export const auth = betterAuth({
  advanced: {
    crossSubDomainCookies: {
      enabled: true,
      domain: ".yourcompany.com",
    },
  },
  trustedOrigins: [
    "https://app.yourcompany.com",
    "https://api-qa.yourcompany.com", // your FlowMock proxy host
  ],
});

Without crossSubDomainCookies, Better Auth sets the cookie for staging-api.yourcompany.com only, and the browser will not send it to api-qa.yourcompany.com. Without the proxy host in trustedOrigins, Better Auth rejects sign-in requests that arrive through the proxy as cross-origin.

OAuth / Google login

OAuth providers redirect the browser back to the callback URL you registered with them. That URL has to be the one the browser actually hits. If your app is pointed at the FlowMock proxy, the callback is on the proxy host - for example https://api-qa.yourcompany.com/auth/callback/google - not on your staging API directly.

Two things need to line up:

  • The callback URL registered in the provider console (Google Cloud, GitHub, etc.) uses the proxy host.
  • Your auth library's base URL (baseURL in Better Auth, NEXTAUTH_URL in NextAuth, and so on) is the proxy host too, so the state and redirect it generates match what the provider sends back.

If the provider returns redirect_uri_mismatch, one of those two is still pointing at the staging host.

Testing locally

For local dev, you might use a tunnel (ngrok, Cloudflare Tunnel) with HTTPS. FlowMock's connect guide in the dashboard walks through this. The key principle is the same: your app and the proxy URL need to agree on cookie domains.