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

# Authentication

> Set up user authentication with Auth0.

<Info>
  Auth0 free tier gives you 25,000 monthly active users.
</Info>

## Setup Auth0

<Steps>
  <Step title="Create Auth0 Account">
    1. Go to [auth0.com](https://auth0.com) and sign up
    2. Create a new tenant
    3. Click **Applications** → **Create Application**
    4. Name your application (e.g., "My SaaS App")
    5. Choose **Regular Web Application** → **Next.js**
    6. Click **Create**

    <Note>
      Keep this tab open—you'll need these values in the next step.
    </Note>
  </Step>

  <Step title="Configure Callback URLs">
    In your Auth0 application settings, add these URLs:

    **Allowed Callback URLs:**

    ```
    http://localhost:3000/auth/callback, https://yourapp.com/auth/callback
    ```

    **Allowed Logout URLs:**

    ```
    http://localhost:3000, https://yourapp.com
    ```

    **Allowed Web Origins:**

    ```
    http://localhost:3000, https://yourapp.com
    ```

    <Warning>
      Replace `yourapp.com` with your actual domain before deploying.
    </Warning>

    Click **Save Changes**.
  </Step>

  <Step title="Add Keys to Your App">
    Copy these values from Auth0 settings:

    * **Domain** (e.g., `dev-xyz123.us.auth0.com`)
    * **Client ID**
    * **Client Secret** (click "Show" to reveal)

    Add them to `.env.local`:

    ```bash .env.local theme={null}
    AUTH0_DOMAIN=
    AUTH0_CLIENT_ID=
    AUTH0_CLIENT_SECRET=
    AUTH0_SECRET=
    APP_BASE_URL=http://localhost:3000
    ```

    Generate `AUTH0_SECRET`:

    ```bash Terminal theme={null}
    openssl rand -hex 32
    ```

    Copy the output and paste it after `AUTH0_SECRET=`
  </Step>

  <Step title="Test It">
    Restart your dev server:

    ```bash Terminal theme={null}
    npm run dev
    ```

    Click **Sign In** in your header. You should see the Auth0 login screen.

    Create an account and sign in. Done.
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Advanced">
    ## Add Social Logins

    Google login is enabled by default but needs verification for production.

    <Accordion title="Add Google Login (Production)">
      1. Go to [Google Cloud Console](https://console.cloud.google.com)
      2. Create a new project and open it
      3. Create OAuth credentials
         1. Open **OAuth consent screen** and fill in the required fields
         2. After that, click **Create OAuth client ID**
         3. Choose **Web application**
         4. Set **Authorized JavaScript origins** to your domain\
            e.g. `https://yourdomain.com`
         5. Set **Authorized redirect URIs** to your Auth0 callback URL\
            e.g. `https://xxxxxxxxxx.auth0.com/login/callback`
         6. Click **Create** and save the credentials (**Client ID** and **Client Secret**)
      4. In Auth0, go to **Authentication** → **Social** → **Google**
      5. Paste the Google Client ID and Client Secret
      6. Save
      7. Done. Google social login is now configured and ready to use in production.
    </Accordion>

    <Accordion title="Add GitHub Login">
      1. Go to [GitHub Settings](https://github.com/settings/developers)
      2. Click **New OAuth App**
      3. Fill in:
         * **Application name:** Your App Name
         * **Homepage URL:** `https://yourapp.com`
         * **Callback URL:** `https://YOUR_AUTH0_DOMAIN/login/callback`
      4. Copy Client ID and Secret
      5. In Auth0: **Authentication** → **Social** → **GitHub**
      6. Add credentials and enable
    </Accordion>

    <Accordion title="Add More Providers">
      Auth0 supports 30+ providers including Microsoft, Apple, Twitter/X, and LinkedIn.

      Go to **Authentication** → **Social** to configure additional providers.
    </Accordion>

    ## How It Works

    1. User clicks "Sign In"
    2. Your app redirects to Auth0
    3. Auth0 shows login form
    4. User enters credentials
    5. Auth0 redirects back with session
    6. User sees dashboard

    ## Customization

    <AccordionGroup>
      <Accordion title="Customize Login Screen">
        In Auth0 dashboard:

        1. Go to **Branding** → **Universal Login**
        2. Upload your logo
        3. Set brand colors
        4. Save changes
      </Accordion>

      <Accordion title="Require Email Verification">
        1. **Settings** → **Tenant Settings** → **General**
        2. Enable "Require email verification"
        3. Customize email templates in **Branding** → **Email Templates**
      </Accordion>
    </AccordionGroup>

    ## Troubleshooting

    <AccordionGroup>
      <Accordion title="Callback URL mismatch error">
        * Check URLs in Auth0 settings match exactly
        * No trailing slashes
        * Include both localhost and production URLs
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

***