Add User Auth to Your App

floo manages user authentication for your deployed apps. When you set access_mode = "accounts", the floo gateway puts a hosted sign-in flow in front of your app, validates each user’s session, and injects identity headers into every request before it reaches your code. You write no auth code. No login pages. No session storage. No OAuth flow. Your app reads X-Floo-User-Email from the request headers and renders a personalized response. That’s the whole integration.

Quickstart

Three steps from a deployed app to per-user sign-in.

1. Set the access mode

In floo.app.toml:

[app]
name = "my-app"
access_mode = "accounts"

[services.web]
type = "web"
port = 3000
ingress = "public"

That’s the entire auth config. There is no [auth] section to add, no callback URLs to register, no client ID to provision.

2. Deploy

git push origin main

When the deploy completes, every request to https://my-app-dev.on.getfloo.com (and the prod URL after promotion) is intercepted by the floo gateway. Unauthenticated visitors are redirected to a hosted sign-in page powered by floo’s WorkOS integration — they can sign in with email magic link, Google, GitHub, or any provider you’ve enabled in your org settings.

3. Read the user from request headers

Every request that reaches your app’s container has the signed-in user attached:

X-Floo-User-Email: jane@acme.com
X-Floo-User-Id:    01HQK4...
X-Floo-User-Name:  Jane Doe
X-Floo-User-Role:  member

Read them like any other header. Examples for each major stack are in the Build with… guides.

Your app has per-user auth. The gateway redirects unauthenticated requests, manages the session cookie, and tells you who the user is on every request. Your app code did not change to make this work.

What gateway-managed auth gives you


Hosted sign-in page	Branded login flow served by floo (email magic link, Google, GitHub, and any provider you’ve enabled in your org settings). The gateway redirects unauthenticated visitors automatically — your app never sees the sign-in flow.
Session management	A signed `__floo_session` cookie, validated on every request, rolled forward as users stay active, revoked on sign-out.
Identity headers	`X-Floo-User-Email`, `X-Floo-User-Id`, `X-Floo-User-Name`, `X-Floo-User-Role` injected into every authenticated request.
Logout endpoint	`POST` (or `DELETE`) `/__floo/logout` clears the session and redirects to the floo login page. After re-login the user lands at the app root `/`. GET is rejected with 405 — see the sign-out section below for why.
User profile JSON	`GET /__floo/me` returns `{ user_id, email, name, role }`. Useful for client-side code that needs the user without parsing headers.
Per-app user list	Every signed-in user appears in your app’s Users tab in the dashboard. First-seen, last-active, sign-in count — for free.
Access policies	Restrict sign-in to your team (`@acme.com` only), specific invited users, or open enrollment.

By default, anyone with a valid email can sign in. Restrict access in three ways.

Company domain allowlist

In the dashboard, under App → Users → Access, add your company email domain (e.g. acme.com). Only users whose verified email matches will be allowed in. Consumer mailbox providers (gmail.com, outlook.com, etc.) are rejected by default.

Invite-only

Set the access policy to invite-only and add specific emails. Users not on the list see an “access denied” page after authenticating.

Declarative access policy

Configure access policy and allowlisted company domains directly in floo.app.toml:

[auth]
access_policy = "domain"          # "open", "invite", or "domain"
allowed_domains = ["acme.com"]    # required when access_policy = "domain"

Both fields sync to the App on every deploy. The dashboard’s per-app Access tab is the alternative — same fields, edited through the UI. Domain allowlists are a Pro+ feature; consumer mailbox providers (gmail.com, outlook.com, etc.) are rejected by default.

Access modes

Mode	Description	Plan
`public`	No auth, anyone can access	All
`password`	Shared app password for simple protection	Pro+
`accounts`	Per-user auth via gateway-managed sign-in	Pro+
`sso`	Enterprise SSO via SAML/OIDC (coming soon)	Enterprise

Per-environment overrides

[app]
name = "my-app"
access_mode = "accounts"

[environments.dev]
access_mode = "public"

The override wins for that environment. Common pattern: public in dev so iteration is fast, accounts in prod.

Password-protected apps

For a single shared password (no user accounts), set the access mode in floo.app.toml:

[app]
access_mode = "password"

The platform generates the shared password automatically on the next deploy. Retrieve it with:

floo apps password my-app

Anyone with the password gets in; there is no per-user identity, and identity headers are not injected.

Reading the user in your app

The pattern is the same in every stack: read the request header.

// Express
app.use((req, _res, next) => {
  const email = req.get("x-floo-user-email");
  req.flooUser = email ? {
    email,
    id: req.get("x-floo-user-id"),
    name: req.get("x-floo-user-name"),
  } : null;
  next();
});

# FastAPI
def require_user(
    email: Annotated[str | None, Header(alias="X-Floo-User-Email")] = None,
):
    if not email: raise HTTPException(401)
    return email

# Rails
class ApplicationController < ActionController::Base
  before_action :load_floo_user
  private
  def load_floo_user
    @current_user_email = request.headers["X-Floo-User-Email"]
  end
end

For full stack-specific examples, see the Build with… guides.

`/__floo/me` — fetch the user as JSON

For client-side code that needs the user object, hit /__floo/me from the browser:

const res = await fetch("/__floo/me");
const user = await res.json();
// { user_id, email, name, role }

Returns 401 if the session is missing or expired. The endpoint is on your app’s own host, so no CORS to configure.

`/__floo/logout` — sign out

/__floo/logout accepts POST and DELETE. Other methods (including GET) return 405 Method Not Allowed with Allow: POST, DELETE. On a successful POST/DELETE the gateway clears the __floo_session cookie, invalidates the session in floo’s session store, and returns 302 to the floo managed-auth login page. After the user signs back in they land at the app’s root (/) — not the page they were on when they signed out. Why no plain <a href="/__floo/logout"> link? The session cookie is SameSite=Lax, which still sends the cookie on cross-origin top-level GET navigation (a malicious link the user clicks, or a window.location redirect from another tab). A GET-served logout was reachable from any other site and could force a sign-out. POST and DELETE are not sent cross-origin under Lax under any condition, so restricting to those methods closes the vector. Sign-out clears floo’s session, not the upstream identity provider. If the user originally signed in via WorkOS and their WorkOS session is still active, the next visit will silently re-authenticate without a password prompt — exactly like browser SSO across other apps. To force a full re-login, the user has to sign out of the IdP separately. (Single-Logout / federated sign-out is not yet supported.) Form button (POST):

<form method="POST" action="/__floo/logout">
  <button type="submit">Sign out</button>
</form>

Rails / Turbo:

<%= button_to "Sign out", "/__floo/logout", method: :delete %>

or with Turbo’s data attribute on a link:

<%= link_to "Sign out", "/__floo/logout", data: { turbo_method: :delete } %>

JavaScript fetch:

await fetch("/__floo/logout", { method: "POST", redirect: "manual" });
window.location.href = "/";  // browser won't follow 302 from fetch with manual redirect

Local development

The floo gateway isn’t in the request path locally, so by default no identity headers reach your app. You have two options.

Use `floo dev --fixture-user`

For accounts-mode apps, floo dev --fixture-user EMAIL starts a small in-process proxy in front of each service that injects the same X-Floo-User-* headers floo’s gateway adds in production:

floo dev --app my-app --fixture-user you@example.com

Output shows two URLs per service — the raw service URL and the auth-proxied URL:

Service   Port   URL                       Auth-proxied URL
─────────────────────────────────────────────────────────────────
web       3000   http://localhost:3000     http://localhost:14732

Hit the auth-proxied URL when you want to test signed-in flows — your app sees X-Floo-User-Email, X-Floo-User-Id, X-Floo-User-Name, and X-Floo-User-Role exactly as it would in production. Hit the raw URL for unauthenticated paths or quick checks. Optional flags fill in the rest of the fixture user (defaults shown):

Flag	Default
`--fixture-id ID`	`dev-fixture-<email-localpart>`
`--fixture-name NAME`	the email
`--fixture-role ROLE`	`member`

The proxy only runs for apps with access_mode = "accounts" — if you pass --fixture-user against any other access mode, floo dev warns and skips the proxy.

Inject the headers yourself

For one-off curl testing, scripts, or stacks where you’d rather skip the proxy entirely:

curl -H "X-Floo-User-Email: you@example.com" \
     -H "X-Floo-User-Id: dev-user-1" \
     -H "X-Floo-User-Name: You" \
     http://localhost:3000/dashboard

Or wrap your header-reading helper to fall back to a fixture user when process.env.NODE_ENV === "development" (or your stack’s equivalent).

Troubleshooting

The session cookie isn’t sticking. Most likely your app sits behind a TLS-terminating proxy that strips Set-Cookie headers, or you’ve misconfigured a custom domain. Check the app’s response headers — a successful login sets __floo_session on the app’s host.

Identity headers are missing from requests

The app probably wasn’t redeployed after setting access_mode = "accounts". Push (or floo redeploy --app my-app) to pick up the gateway routing change. You haven’t configured an access policy. Set a domain allowlist in the dashboard or in floo.app.toml under [auth].access_policy. The gateway redirects to the original requested URL after sign-in — so just link unauthenticated users to the deep link they wanted, and the gateway does the right thing. To force a landing page, redirect from / based on X-Floo-User-Email.

Build a stack-specific app

Stack journeys (Rails, Next.js, FastAPI, Django, Express) showing the full deploy + auth flow.

Team Access

Org membership, app access policies, and password-protected apps.

Internal Tools

Why managed auth is the right answer for internal tools — and how a domain allowlist gives you a per-team app in one config change.

Custom Domains

Put your auth-protected app on app.yourcompany.com.

Get Started

Build with...

Build your app

Environments

Managed Services

Observe

Access

For Agents

Add User Auth to Your App

Quickstart

1. Set the access mode

2. Deploy

3. Read the user from request headers

What gateway-managed auth gives you

Company domain allowlist

Invite-only

Declarative access policy

Access modes

Per-environment overrides

Password-protected apps

Reading the user in your app

`/__floo/me` — fetch the user as JSON

`/__floo/logout` — sign out

Local development

Use `floo dev --fixture-user`

Inject the headers yourself

Troubleshooting

Identity headers are missing from requests

Build a stack-specific app

Team Access

Internal Tools

Custom Domains

Get Started

Build with...

Build your app

Environments

Managed Services

Observe

Access

For Agents

Documentation Index

​Quickstart

​1. Set the access mode

​2. Deploy

​3. Read the user from request headers

​What gateway-managed auth gives you

​Restrict who can sign in

​Company domain allowlist

​Invite-only

​Declarative access policy

​Access modes

​Per-environment overrides

​Password-protected apps

​Reading the user in your app

​/__floo/me — fetch the user as JSON

​/__floo/logout — sign out

​Local development

​Use floo dev --fixture-user

​Inject the headers yourself

​Troubleshooting

​Users see a login page on every request

​Identity headers are missing from requests

​Users from outside my company can sign in

​I want users to land on a specific page after login

Build a stack-specific app

Team Access

Internal Tools

Custom Domains

Quickstart

1. Set the access mode

2. Deploy

3. Read the user from request headers

What gateway-managed auth gives you

Restrict who can sign in

Company domain allowlist

Invite-only

Declarative access policy

Access modes

Per-environment overrides

Password-protected apps

Reading the user in your app

`/__floo/me` — fetch the user as JSON

`/__floo/logout` — sign out

Local development

Use `floo dev --fixture-user`

Inject the headers yourself

Troubleshooting

Users see a login page on every request

Identity headers are missing from requests

Users from outside my company can sign in

I want users to land on a specific page after login