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

# Authentication

> Better Auth + GitHub OAuth flow in OpenChat.

# Authentication

OpenChat uses Better Auth with GitHub OAuth, then syncs users into Convex.

<img className="rounded-xl" src="https://mintcdn.com/osschat/0XVzE_uVrSJzBV70/images/openchat/landing/osschat-signin-page-dark.png?fit=max&auto=format&n=0XVzE_uVrSJzBV70&q=85&s=8ffb365fb475f188de3d980df81dbeae" alt="OpenChat GitHub OAuth sign-in screen in dark mode" width="1600" height="1000" data-path="images/openchat/landing/osschat-signin-page-dark.png" />

## Request Flow

```mermaid theme={null}
sequenceDiagram
  participant U as User
  participant W as Web App
  participant B as Better Auth
  participant G as GitHub
  participant C as Convex
  U->>W: Sign in
  W->>B: Start OAuth
  B->>G: Redirect
  G->>B: Callback
  B->>W: Session established
  W->>C: users.ensure
```

## Key Implementation Points

* Client auth state from `auth-client.tsx` via `useAuth()`.
* Server-side auth helpers in `server-auth.ts`.
* Root route preloads session in `routes/__root.tsx`.
* Route-level guards in pages such as `routes/c/$chatId.tsx` and `routes/settings.tsx`.

## Required Variables

```bash theme={null}
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
BETTER_AUTH_SECRET=...
VITE_CONVEX_SITE_URL=...
```

<Warning>
  Callback URL must target the Convex site URL host: `/api/auth/callback/github`.
</Warning>

## Security Notes

* Same-origin checks are enforced on sensitive server handlers.
* Convex user identity is validated before database access.
* Rate limits protect auth-adjacent workflow endpoints.