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

# Authentication

> Manage users and authentication.

<Card title="POST /api/auth/login" href="#login">
  Log in to get a JWT token.
</Card>

<Card title="POST /api/auth/register" href="#register">
  Register a new user.
</Card>

<Card title="GET /api/auth/user" href="#get-current-user">
  Get the currently authenticated user.
</Card>

<Card title="POST /api/auth/change-password" href="#change-password">
  Change the password for the current user.
</Card>

***

### Login

Authenticates a user and returns a JWT token along with user details.

* **Endpoint**: `/api/auth/login`
* **Method**: `POST`
* **Body**:
  * `username` (string, required): The user's username.
  * `password` (string, required): The user's password.
* **Request Example**:
  ```json theme={null}
  {
    "username": "admin",
    "password": "your-admin-password"
  }
  ```
* **Success Response**:
  ```json theme={null}
  {
    "success": true,
    "message": "Login successful",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "admin",
      "isAdmin": true,
      "permissions": { ... }
    }
  }
  ```

***

### Register

Registers a new user and returns a JWT token.

* **Endpoint**: `/api/auth/register`
* **Method**: `POST`
* **Body**:
  * `username` (string, required): The desired username.
  * `password` (string, required): The desired password (must be at least 6 characters).
  * `isAdmin` (boolean, optional): Whether the user should have admin privileges.
* **Request Example**:
  ```json theme={null}
  {
    "username": "newuser",
    "password": "password123",
    "isAdmin": false
  }
  ```
* **Success Response**:
  ```json theme={null}
  {
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "newuser",
      "isAdmin": false,
      "permissions": { ... }
    }
  }
  ```

***

### Get Current User

Retrieves the profile of the currently authenticated user.

* **Endpoint**: `/api/auth/user`
* **Method**: `GET`
* **Authentication**: Bearer Token required.
* **Success Response**:
  ```json theme={null}
  {
    "success": true,
    "user": {
      "username": "admin",
      "isAdmin": true,
      "permissions": { ... }
    }
  }
  ```

***

### Change Password

Allows the authenticated user to change their password.

* **Endpoint**: `/api/auth/change-password`
* **Method**: `POST`
* **Authentication**: Bearer Token required.
* **Body**:
  * `currentPassword` (string, required): The user's current password.
  * `newPassword` (string, required): The desired new password (must be at least 6 characters).
* **Request Example**:
  ```json theme={null}
  {
    "currentPassword": "oldpassword",
    "newPassword": "newpassword123"
  }
  ```
* **Success Response**:
  ```json theme={null}
  {
    "success": true,
    "message": "Password updated successfully"
  }
  ```

***

### Social Login (Better Auth)

Pcnaid MCP Hub integrates [Better Auth](https://www.better-auth.com/) to provide seamless social login capabilities (GitHub, Google, etc.).

**Prerequisites**:

1. **Database Mode**: `DB_URL` environment variable must be configured (PostgreSQL is required for Better Auth persistence).
2. **Provider Configuration**:
   * **GitHub**: Set `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`.
   * **Google**: Set `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`.

**Endpoints**:
The Better Auth API is mounted at `/api/auth/better`. Key endpoints include:

* **Initiate Login**:
  * `GET /api/auth/better/signIn/social?provider=github`
  * `GET /api/auth/better/signIn/social?provider=google`

* **Session Management**:
  * `GET /api/auth/better/session` (Get current session)
  * `POST /api/auth/better/signOut` (Sign out)

For a complete list of endpoints and usage details, refer to the [Better Auth API Documentation](https://www.better-auth.com/docs).

**Disabling Better Auth**:

Better Auth will also be automatically disabled if `DB_URL` is not configured, or if no social login providers are configured with their required environment variables.