Source: https://www.hype-stack.dev/docs/packs-templates/packs/starter-auth-betterauth

# Auth Starter (Better Auth)

The free starter. Sign in, sessions, password reset, email verification, a profile page, and a minimal admin console,
powered by [Better Auth](https://www.better-auth.com) on your own Postgres. This is the `starter-auth-betterauth` pack.
No organizations to manage, no invitations, no onboarding, no user directory.

```bash
npx @hype-stack/cli compose --packs starter-auth-betterauth,layout-basic
```

For session flow, middleware, and route guards, see [Authentication](/docs/backend/authentication).

## What you get

- Email/password and Google sign-in, with the same callback handling as the SaaS starters
- Server-side sessions in signed cookies, refresh and validation middleware
- Password reset and email verification through Resend
- A settings page with a profile tab (name, avatar), and the settings-tabs registry feature packs extend
- The same `/users/me` contract, CASL permission layer, and `hasAccess` middleware the SaaS starters ship
- An admin console with its own login, admin management for super admins, and a dashboard that feature packs fill
- Mobile and browser-extension slots with the auth screens and the profile screen

## The personal workspace

Every account gets an organization named `Personal workspace` the moment it is created, and every session opens inside
it. You never see it: there is no switcher, no members page, no invitations. It exists because every feature pack scopes
its data to the active organization, and it is what makes them install on this starter exactly as they do on a SaaS one.
Billing, projects, calendar, whiteboard, teams, newsletter, and cookies all work here.

The backend also keeps the invitation inbox (pending, accept, decline) so the notifications pack, which reads it,
installs unchanged. Nothing on the free starter can send an invitation, so the inbox stays empty until you swap to a
SaaS starter.

## Growing into a SaaS starter

When you need teams, invitations, or the user and organization directories in the admin console, swap the starter:

```bash
npx @hype-stack/cli compose --packs starter-saas-betterauth
```

The schema is the SaaS starters' schema, so there is no migration: the personal workspace becomes the user's first team.
The CLI replaces the files both starters ship, removes the ones only the free starter had, re-applies your layout, and
leaves your own files alone. The WorkOS starter is the same swap with `starter-saas-workos`.

## What you need

- A **Google OAuth** web app, if you want Google sign-in. Optional; without the keys the button is not offered.
- **Resend** for transactional email (password reset, email verification). Uses the base template's `RESEND_API_KEY`.
- Postgres and Valkey (base services).

## Environment variables

| Variable                    | Purpose                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `BETTER_AUTH_URL`           | Origin Better Auth runs on (e.g. `http://localhost:3000`)                                |
| `BETTER_AUTH_SECRET`        | Auth secret. The CLI generates one at install time                                       |
| `GOOGLE_CLIENT_ID`          | Google OAuth client ID (optional)                                                        |
| `GOOGLE_CLIENT_SECRET`      | Google OAuth client secret (optional)                                                    |
| `MOBILE_OAUTH_REDIRECT_URL` | Deep link the Expo app returns to after Google sign-in (default `hypestack://callback`)  |
| `RESEND_API_KEY`            | Transactional email (password reset, verification)                                       |
| `SUPER_ADMIN_EMAIL`         | Comma-separated emails that can sign in to the admin console before any admin row exists |

The Google callback is `/api/auth/callback/google` appended to your `BETTER_AUTH_URL`, the same as for the SaaS starter.
See [SaaS Starter (Better Auth)](/docs/packs-templates/packs/starter-saas-betterauth) for the Google Cloud Console
steps.

## The admin console

The admin app is the minimal one. Super admins sign in (bootstrap the first with `SUPER_ADMIN_EMAIL` in
`apps/backend/.env`), and the Settings page is where they add and remove console admins and set their role. The
dashboard starts empty: it is the registry feature packs inject into, so installing billing puts its revenue row there.
There is no users page and no organizations page; those come with a SaaS starter.