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

# Authentication

> Zeus user authentication system (Better Auth)

# Better Auth

## Overview

Zeus uses **Better Auth** as its authentication solution, supporting email/password login and social login (GitHub, Google).

## Architecture

```mermaid theme={null}
flowchart TD
    subgraph Frontend
        SignIn["Sign In Page<br/>- Email/Password<br/>- GitHub OAuth<br/>- Google OAuth"]
        SignUp["Sign Up Page<br/>- Email/Password<br/>- GitHub OAuth<br/>- Google OAuth"]
    end

    API["Next.js API Routes<br/>/api/auth/[...all]<br/>Better Auth handles all auth endpoints"]

    subgraph BAS["Better Auth Server"]
        Features["- User registration/login<br/>- Session management<br/>- OAuth flow<br/>- JWT token issuance"]
    end

    subgraph DB["PostgreSQL"]
        Tables["user, session, account<br/>verification, jwks<br/>native_refresh_token"]
    end

    Frontend --> API
    API --> BAS
    BAS --> DB
```

## GitHub Login Flow

```mermaid theme={null}
flowchart TD
    A["User clicks 'Sign in with GitHub'"] --> B["Frontend calls authClient.signIn.social"]
    B --> C["Redirect to GitHub authorization page"]
    C --> D["User authorizes, GitHub calls back to<br/>/api/auth/callback/github"]
    D --> E["Better Auth handles callback:<br/>- Fetches user info<br/>- Creates/updates user record<br/>- Creates account record<br/>- Creates session<br/>- Sets session_token cookie"]
    E --> F["Redirect to home page"]
```

## Native Client Authentication (Desktop / iOS)

Desktop and iOS native clients use a **dual-token mechanism**:

| Token Type            | Validity | Storage                            |
| --------------------- | -------- | ---------------------------------- |
| accessToken (JWT)     | 1 hour   | Desktop: JSON file / iOS: Keychain |
| refreshToken (opaque) | 30 days  | Desktop: JSON file / iOS: Keychain |

* Both tokens are issued at login (via `/api/auth/jwt` or device authorization flow)
* Before each API call, the client checks if the accessToken is about to expire (\< 5 minutes)
* When expired, the client automatically calls `POST /api/auth/refresh` to get a new accessToken
* If the refreshToken is also expired, the user is automatically logged out

See [Refresh Token API](/en/api-reference/auth/refresh-token) and [JWT Service Authentication](/en/documentation/infra/auth) for details.

## Related Documentation

<CardGroup cols={2}>
  <Card title="JWT Service Authentication" icon="key" href="/en/ai-backend/infra/Auth">
    Dual-layer JWT authentication between Web and AI Backend
  </Card>

  <Card title="Database" icon="database" href="/en/web/Database">
    Authentication-related database tables (user, session, account)
  </Card>
</CardGroup>