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

# Authentication

> Email/password auth, session management, and route protection via Supabase and proxy.ts.

# Authentication

The template uses [Supabase Auth](https://supabase.com/docs/guides/auth) with email/password sign-in, email verification, and password reset. Session management runs through a Next.js middleware-style proxy that refreshes tokens and enforces route protection on every request.

## Auth Routes

| Route                          | Purpose                                      |
| ------------------------------ | -------------------------------------------- |
| `/auth/login`                  | Sign in page                                 |
| `/auth/register`               | Sign up page                                 |
| `/auth/reset-password`         | Request password reset email                 |
| `/auth/reset-password/confirm` | Set new password (after clicking email link) |
| `/auth/callback`               | OAuth / email verification callback          |
| `/auth/error`                  | Auth error display                           |

## Email Verification

Email confirmation is enabled by default (`enable_confirmations = true` in `supabase/config.toml`). After registration, users receive a verification email. The `RegisterForm` shows a "check your email" state with a resend option. The `LoginForm` handles the `email_not_confirmed` error with an inline resend banner.

<Note>
  During local development, Supabase routes emails through Inbucket ([http://localhost:54324](http://localhost:54324)) so you never need real SMTP credentials to test the flow.
</Note>

## Three Supabase Client Patterns

The app exposes three client patterns, all re-exported from `@/lib/supabase`:

```typescript theme={null}
// Client Components — runs in the browser
import { createBrowserClient } from "@/lib/supabase/client";

// Server Components and Route Handlers
import { createServerClient } from "@/lib/supabase/server";

// Service-role operations — bypasses RLS. Server only, never import in client code.
import { createAdminClient } from "@/lib/supabase/admin";
```

The admin client requires `SUPABASE_SERVICE_ROLE_KEY` and should only be used in server actions or API routes for operations that need to bypass Row Level Security (e.g., creating users, reading across workspaces).

## Session Management

`proxy.ts` runs on every request (via Next.js middleware) and does two things:

1. **Refreshes the Supabase session** — calls `supabase.auth.getUser()` so the token is kept alive and written back to cookies.
2. **Enforces route protection** — redirects unauthenticated users away from protected routes, and redirects authenticated users away from auth routes.

Configuration lives in `saas.config.ts`:

```typescript theme={null}
auth: {
  protectedRoutes: ["/dashboard", "/settings", "/workspaces", "/admin"],
  publicRouteOverrides: ["/invitations/accept"],
  authRoutes: ["/", "/auth/login", "/auth/register"],
  afterLoginRedirect: "/dashboard",
  loginPath: "/auth/login",
}
```

Add any new protected route prefixes to `protectedRoutes`. Add paths that begin with a protected prefix but handle their own auth (e.g., public invite acceptance) to `publicRouteOverrides`.

## Auth Context (Client Components)

Wrap your app with `AuthProvider` (already done in the root layout) and read auth state anywhere with `useAuth()`:

```typescript theme={null}
import { useAuth } from "@/lib/auth/context";

export function MyComponent() {
  const { user, session, isLoading, isSuperAdmin } = useAuth();
  if (isLoading) return null;
  if (!user) return <p>Not signed in</p>;
  return <p>Hello, {user.email}</p>;
}
```

`isSuperAdmin` is fetched from `profiles.is_super_admin` on sign-in. The provider also handles automatic token refresh and listens to auth state changes.

## Password Reset Flow

<Steps>
  <Step title="User requests reset">
    POST to `/auth/reset-password` — Supabase sends a recovery email.
  </Step>

  <Step title="User clicks email link">
    Lands on `/auth/callback`, which exchanges the token and redirects to `/auth/reset-password/confirm`.
  </Step>

  <Step title="User sets new password">
    `UpdatePasswordForm` calls `supabase.auth.updateUser({ password })`.
  </Step>
</Steps>

## Environment Variables

| Variable                        | Required | Description                    |
| ------------------------------- | -------- | ------------------------------ |
| `NEXT_PUBLIC_SUPABASE_URL`      | Yes      | Your Supabase project URL      |
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Yes      | Supabase anon/public key       |
| `SUPABASE_SERVICE_ROLE_KEY`     | Yes      | Service role key (server-only) |