Auth

With 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, login page, session store, or OAuth flow. Your app reads X-Floo-User-Email from the request headers.

Quickstart

1. Set the access mode

In floo.app.toml:

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

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

That is the entire auth config for invite-only sign-in: no callback URLs to register and no client ID to provision. An optional [auth] block sets the sign-in policy and branding.

2. Deploy

git push origin main

Once the deploy is live, the floo gateway intercepts every request to https://my-app-dev.getfloo.app (and the prod URL after promotion). Invited users sign in with their floo account through the hosted sign-in page, including Google and the other providers configured for floo.

3. Read the user from request headers

Every request that reaches your app carries the signed-in user:

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, with no change to your app code.

What gateway-managed auth gives you


Hosted sign-in page	floo sign-in, including Google and configured providers. 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; the sign-out section below explains why.
User profile JSON	`GET /__floo/me` returns `{ user_id, email, name, role }` for client-side code that needs the user without parsing headers.
Explicit app members	Every authorized person has one app membership with a `member` or `admin` tenant role. App access does not grant dashboard or deployment access.
Immediate revocation	Removing a member revokes their app sessions and user-bound app keys. Changing a role signs out sessions that carry stale role authority.

Invite app users

Accounts-mode apps are invite-only. Invite a person from App → Access in the dashboard or from the CLI:

floo apps invite teammate@acme.com --role member --app my-app

The recipient creates or reuses a floo account with that email, then accepts the app membership. Their account can use only the apps they were explicitly invited to; it does not grant dashboard, organization, deployment, billing, or platform API-key access. Use floo apps invites --app my-app to inspect pending invitations. Resending rotates the old link, and revoking makes it unusable immediately. Use floo apps members --app my-app to list active app members and copy the IDs needed for role changes or removal. An organization member is not automatically an app user. The app’s creator gets an explicit admin membership when the app is created; invite other operators to the apps they should use.

Access modes

Mode	Description	Plan
`public`	No auth, anyone can access	All
`accounts`	Per-user auth via gateway-managed sign-in	Pay as you go+

For program access, set access = "api_key" on a route. See App API keys and request history. Enterprise SSO (SAML/OIDC) is a sales-assisted setup, not a self-serve access_mode. Contact sales if your team needs it.

Per-environment overrides

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

[environments.dev]
access_mode = "public"

[environments.<env>] access_mode wins over [app] access_mode for that environment, and each environment resolves on its own: prod never inherits dev’s override. The accepted keys are dev, prod, and preview; any other name, such as [environments.production], fails the deploy rather than being ignored. Common pattern: public in dev so iteration is fast, accounts in prod.

Password-protected apps

Shared-password access was retired in platform release v2026.10.07.1. Use accounts for per-user sign-in or app API keys for program access.

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

Client-side code can fetch the user object from /__floo/me:

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 there is 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 signing back in, the user lands at the app’s root (/), not the page they signed out from. 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 signed in through an identity provider such as Google and that provider’s 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 identity provider 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 is not in the request path locally, so no identity headers reach your app unless you add them.

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

Use the auth-proxied URL 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 in production. Use the raw URL for unauthenticated paths. 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 runs only for apps with access_mode = "accounts". With any other access mode, floo dev warns and skips the proxy.

Inject the headers yourself

For one-off curl tests, scripts, or skipping the proxy:

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 is not sticking. Check the app’s response headers: a successful login sets __floo_session on the app’s host. If the cookie is absent, a proxy between floo’s edge and the browser is stripping Set-Cookie, or the custom domain is misconfigured; run floo doctor accounts --app my-app to see the gateway state serving the app.

Identity headers are missing from requests

The app has not been redeployed since access_mode = "accounts" was set. Push (or floo redeploy --app my-app) to pick up the gateway routing change. Admission is invitation-only under every access_policy value: only people with an active app membership get in. List members with floo apps members --app my-app and remove anyone unexpected with floo apps member-remove. The gateway redirects to the original requested URL after sign-in, so link unauthenticated users straight to the deep link they wanted. 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 and access control

Org membership, app access policies, and app users.

Custom domains

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

Get started

Build with your stack

Deploy

Managed services

Environments

Operate

Access

For agents

Quickstart

1. Set the access mode

2. Deploy

3. Read the user from request headers

What gateway-managed auth gives you

Invite app users

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 and access control

Custom domains

​Quickstart

​1. Set the access mode

​2. Deploy

​3. Read the user from request headers

​What gateway-managed auth gives you

​Invite app users

​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 and access control

Custom domains

Quickstart

1. Set the access mode

2. Deploy

3. Read the user from request headers

What gateway-managed auth gives you

Invite app users

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