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

# Authentication

> Set up sign-in for your app with email/password, Google OAuth, magic links, and password resets

Your app ships with a full authentication system powered by [Better Auth](https://www.better-auth.com/). It runs inside your Next.js app and talks directly to your Drizzle database -- no external auth service needed.

<Tip>
  Recommended path: run `pnpm bootstrap`. The setup wizard generates `BETTER_AUTH_SECRET`, writes `.env.local`, and can prompt for Google OAuth and email-provider settings. The rest of this page is the manual setup path.
</Tip>

## What's Already Built For You

Out of the box, you get:

* A polished login page at `/auth`
* Email/password sign-in and sign-up
* Google OAuth sign-in (optional)
* Magic link sign-in (optional)
* Forgot-password / reset flow
* Session handling and protected routes
* Automatic redirects into your app after login

<Info>
  The key routes to know: `/auth` (sign-in page), `/auth/reset-password` (password reset),
  `/api/auth/[...all]` (Better Auth handler), and `/api/auth/callback/google` (Google OAuth callback).
</Info>

## Getting Started

<Steps>
  <Step title="Run the setup wizard (recommended)">
    ```bash theme={null}
    pnpm bootstrap
    ```

    Choose the auth options you want, and the wizard will write the matching `.env.local` values for you.
  </Step>

  <Step title="Or set your core env vars manually">
    These three variables are the absolute minimum to get auth working:

    ```env theme={null}
    NEXT_PUBLIC_APP_URL=http://localhost:3000
    BETTER_AUTH_SECRET=...
    DATABASE_URL=postgresql://...
    ```

    <Tip>
      `BETTER_AUTH_URL` is optional. If you skip it, the app automatically falls back to `NEXT_PUBLIC_APP_URL`.
    </Tip>
  </Step>

  <Step title="Pick your auth methods">
    With just the core env vars above, **email/password auth works immediately**. For Google OAuth or magic links, keep reading -- you'll add a few more env vars depending on what you want.
  </Step>

  <Step title="Restart your dev server">
    After changing any env vars, restart your dev server for the changes to take effect.

    ```bash theme={null}
    pnpm dev
    ```
  </Step>
</Steps>

## Auth Method Setup

<Tabs>
  <Tab title="Email / Password">
    This is the default and requires **zero extra configuration** beyond the core env vars above.

    Your users can sign up with an email and password, and sign in the same way. That's it -- you're done!
  </Tab>

  <Tab title="Magic Link">
    Magic link sign-in lets users log in by clicking a link sent to their email. To enable it, you need an email provider configured.

    **Supported email providers:** `loops`, `resend`, `brevo`

    <CodeGroup>
      ```env Loops theme={null}
      NEXT_PUBLIC_EMAIL_PROVIDER=loops
      EMAIL_PROVIDER=loops
      AUTH_EMAIL_FROM="AnotherWrapper <auth@example.com>"
      LOOPS_API_KEY=...
      LOOPS_AUTH_MAGIC_LINK_TRANSACTIONAL_ID=...
      LOOPS_AUTH_RESET_PASSWORD_TRANSACTIONAL_ID=...
      ```

      ```env Resend theme={null}
      NEXT_PUBLIC_EMAIL_PROVIDER=resend
      EMAIL_PROVIDER=resend
      AUTH_EMAIL_FROM="AnotherWrapper <auth@example.com>"
      RESEND_API_KEY=...
      ```

      ```env Brevo theme={null}
      NEXT_PUBLIC_EMAIL_PROVIDER=brevo
      EMAIL_PROVIDER=brevo
      AUTH_EMAIL_FROM="AnotherWrapper <auth@example.com>"
      BREVO_API_KEY=...
      ```
    </CodeGroup>

    <Note>
      `NEXT_PUBLIC_EMAIL_PROVIDER` controls whether the auth UI shows magic-link and reset-password modes. `EMAIL_PROVIDER` is the server-side provider selection and falls back to the public value if you do not override it.
    </Note>
  </Tab>

  <Tab title="Google OAuth">
    Google sign-in is totally optional, but it's a great way to reduce friction for your users.

    <Steps>
      <Step title="Create OAuth credentials">
        Head to the [Google Cloud Console](https://console.cloud.google.com/) and create OAuth 2.0 credentials for your project.
      </Step>

      <Step title="Add your redirect URIs">
        In your Google OAuth settings, add these as allowed redirect URIs:

        * `http://localhost:3000/api/auth/callback/google` (for local dev)
        * `https://yourdomain.com/api/auth/callback/google` (for production)
      </Step>

      <Step title="Set your env vars">
        ```env theme={null}
        GOOGLE_CLIENT_ID=...
        GOOGLE_CLIENT_SECRET=...
        NEXT_PUBLIC_GOOGLE_AUTH_ENABLED=true
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## What Happens When a User Signs In

Here's the flow your users go through:

<Steps>
  <Step title="User lands on /auth">
    They see your sign-in page with the auth methods you've enabled.
  </Step>

  <Step title="Better Auth handles the session">
    Better Auth creates or reads the user and session directly in your database.
  </Step>

  <Step title="Profile sync">
    The app automatically syncs the matching profile row for the user.
  </Step>

  <Step title="Redirect">
    The user lands on `/` (or whatever page they originally requested).
  </Step>
</Steps>

## Verification Checklist

Run through this list to make sure everything is working:

<Check>Email/password sign-in and sign-up works</Check>
<Check>Magic link emails arrive (if you enabled magic links)</Check>
<Check>Password reset emails arrive (if you enabled email auth)</Check>
<Check>Clicking a magic link or reset link signs you in correctly</Check>
<Check>Google sign-in works (if you enabled it)</Check>
<Check>`/` loads after sign-in without bouncing back to `/auth`</Check>

## Troubleshooting

<AccordionGroup>
  <Accordion title="I get an error about BETTER_AUTH_SECRET">
    This env var is required. Generate a random string (at least 32 characters) and set it in your `.env.local` file. Without it, Better Auth can't encrypt sessions.
  </Accordion>

  <Accordion title="Magic link or reset emails aren't arriving">
    Double-check that you've set `AUTH_EMAIL_FROM` and your email provider credentials. If you're using Loops, make sure you've also set the transactional template IDs (`LOOPS_AUTH_MAGIC_LINK_TRANSACTIONAL_ID` and `LOOPS_AUTH_RESET_PASSWORD_TRANSACTIONAL_ID`).
  </Accordion>

  <Accordion title="Google OAuth gives a redirect error">
    The most common cause is a mismatch between your callback URL in Google Cloud and your actual app URL. Make sure your redirect URI is exactly `http://localhost:3000/api/auth/callback/google` for local dev (or your production domain equivalent).
  </Accordion>

  <Accordion title="NEXT_PUBLIC_APP_URL doesn't match my domain">
    This variable must match the domain you're actually testing on. If you're running locally, it should be `http://localhost:3000`. In production, it should be your live domain with `https://`.
  </Accordion>

  <Accordion title="I changed env vars but nothing changed">
    You need to restart your dev server after editing `.env.local`. Kill the running process and run `pnpm dev` again.
  </Accordion>
</AccordionGroup>