> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# User accounts

> Add [managed.<name>.users] to a managed Postgres and your external app gets sign-up and sign-in for its own users, served on your app's domain and stored in your database.

`[managed.<name>.users]` turns on sign-in for the people who use your app: email and password, plus Google, GitHub, Microsoft or Vercel. floo runs the sign-in service ([Better Auth](https://www.better-auth.com)) at `/api/auth` on every host of your app, including custom domains. Users, sessions and accounts live in your app's own Postgres, in the `floo_auth` schema, next to your tables. Your app renders its own pages.

## User accounts or team access

| | [Team access](https://getfloo.com/docs/guides/app-auth.md) | User accounts |
| - | - | - |
| For | Internal apps | External, consumer-facing apps |
| Who signs in | Your org members and people you invite | Anyone who signs up |
| Where users live | floo accounts | Your app's Postgres |
| Who decides which pages need a user | The floo gateway locks the whole app | Your app |
| Config | `access_mode = "accounts"` | `[managed.<name>.users]` |

They share no config key, header or session. A User accounts app keeps `access_mode = "public"`.

## Turn it on

### 1. Declare it on a managed Postgres

```toml theme={null}
[managed.default]
type = "postgres"

[managed.default.users]
methods = ["email_password", "google"]
signup = "open"
allowed_email_domains = ["duke.edu"]
```

An empty `[managed.default.users]` table means email and password with open sign-up from any address. One Postgres per app can hold User accounts.

### 2. Deploy

The next dev deploy sets up sign-in for dev and prod. After that, `/api/auth` on every host of an environment answers sign-in requests, and settings follow each environment's deploys, so a prod change ships with a release. Each service gets:

| Variable | Value |
| - | - |
| `FLOO_AUTH_URL` | `https://<environment host>/api/auth` |
| `FLOO_AUTH_JWKS_URL` | Public keys for verifying session tokens |

Dev and prod have separate users: a dev user cannot sign in to prod. Preview environments sign in against dev's users.

### 3. Add sign-in to your app

Use the standard [`better-auth`](https://www.better-auth.com/docs) client. Sign-in is on your app's own origin, so the client needs no URL and cookies are first-party:

```ts theme={null}
import { createAuthClient } from "better-auth/react";
import { emailOTPClient } from "better-auth/client/plugins";

export const auth = createAuthClient({ plugins: [emailOTPClient()] });

// Sign up, then confirm the 6-digit code floo emails.
await auth.signUp.email({ email, password, name });
await auth.emailOtp.verifyEmail({ email, otp });

// Sign in, and read the session anywhere in the UI.
await auth.signIn.email({ email, password });
const { data: session } = auth.useSession();

// Forgot password: a code by email, then a new password.
await auth.emailOtp.sendVerificationOtp({ email, type: "forget-password" });
await auth.emailOtp.resetPassword({ email, otp, password: newPassword });
```

An address must be verified before it can sign in. Google, GitHub, Microsoft and Vercel users are verified by the provider: `await auth.signIn.social({ provider: "google" })`.

On the server, check the session with the request's cookie:

```ts theme={null}
const response = await fetch(`${process.env.FLOO_AUTH_URL}/get-session`, {
  headers: { cookie: request.headers.get("cookie") ?? "" },
});
const session = await response.json(); // null when signed out
```

Any other backend can verify a token instead: the browser gets one from `GET /api/auth/token`, and your backend checks it against `FLOO_AUTH_JWKS_URL` (EdDSA).

Session checks are answered from a signed cookie for 5 minutes, so page loads are fast and never wait on your database. Signing out takes effect at once in that browser. A session ended elsewhere (a password reset, or revoking other sessions) can keep working in another browser for up to 5 minutes.

## Settings

| Key | Values | Default |
| - | - | - |
| `methods` | Any of `email_password`, `google`, `github`, `microsoft`, `vercel` | `["email_password"]` |
| `signup` | `"open"` or `"closed"` | `"open"` |
| `allowed_email_domains` | Lowercase domains, e.g. `["duke.edu"]` | Any address |

* `signup = "closed"` stops new sign-ups by every method; existing users still sign in.
* `allowed_email_domains` refuses sign-up from any other address, whatever the method, before an account exists.
* `/api/auth` belongs to floo while User accounts is on: a `[[routes]]` entry at that path is replaced.

Changes usually reach sign-in within 30 seconds of the deploy going live.

## Email

Verification and password-reset codes come from `<your app's name> <noreply@auth.getfloo.app>`. Codes are 6 digits, expire after 10 minutes, and allow 5 tries.

## Testing

In dev, any address at `@test.getfloo.app` signs up and verifies with the code `000000`, and no email is sent. Tests and coding agents can create and sign in users without a mailbox. Prod refuses these addresses. If you set `allowed_email_domains`, it applies to test addresses too: add `"test.getfloo.app"` to the list to use them. Leave it out when real users sign in on your dev environment.

### On your machine

`floo dev` (CLI v2026.11.10 or later) prints a proxied URL next to each service. Open your app on that URL and `/api/auth` goes to your dev environment's sign-in, so sign-up, sign-in and sessions work locally against dev's users, with the session cookie on `localhost`. Every other path goes to your local service. Use a `@test.getfloo.app` address to skip the mailbox. Social sign-in returns to the dev host, so test it there.

## Social sign-in

Each provider needs your own OAuth app in each environment, so the consent screen shows your app's name:

1. Add the provider to `methods` and deploy. Until step 3 that method stays off.
2. Create an OAuth app with the provider. Set its callback URL to `https://<environment host>/api/auth/callback/<provider>`, for example `https://shop.getfloo.app/api/auth/callback/google`. Add one for each custom domain users sign in on.
3. Give floo the client id and secret for that environment:

```http theme={null}
PUT /v1/apps/{app_id}/end-users/oauth/github?env=prod
Content-Type: application/json

{"client_id": "Iv1.abc123", "client_secret": "..."}
```

floo stores the secret encrypted and never returns it. The call is refused with `USER_ACCOUNTS_METHOD_NOT_DECLARED` unless the environment's live deploy lists the provider in `methods`.

## Your users' data

Users are rows in your database. Query them like any table:

```bash theme={null}
floo db query --app my-app 'select id, email, "createdAt" from floo_auth."user" order by "createdAt" desc limit 20' --env prod
```

The sign-in service reaches only the `floo_auth` schema, through its own Postgres role. Removing the `users` table stops sign-in at `/api/auth` on the next deploy; the `floo_auth` data stays in your database.

## Billing

There is no charge per user. Sign-in queries run on your Postgres and bill as Postgres compute.

## Limits

* Ten wrong passwords for one account within 15 minutes pause password sign-in for that account until the 15 minutes pass. Sign-in answers 429 with the message "Too many wrong passwords for this account. Try again in 15 minutes, or reset your password." Resetting the password by emailed code ends the pause, and a correct sign-in before the tenth wrong try clears the count.
* One address gets 20 codes and wrong code guesses an hour per app host, counted together across verification and password reset. Past that, the request answers 429 with "Too many codes for this address. Try again in an hour."
* Apple sign-in, passkeys and magic links are not available.
* Social sign-in on a preview host needs that host's callback URL in your OAuth app.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.