> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcphub.app/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)

MCPHub 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**: Better Auth bootstrap settings are read once at startup, so restart MCPHub after changing them.
3. **Environment Variables**:

* **Global**: `BETTER_AUTH_ENABLED`, `BETTER_AUTH_URL`, optional `BETTER_AUTH_BASE_PATH`, optional `BETTER_AUTH_TRUSTED_ORIGINS`.
* **GitHub**: `BETTER_AUTH_GITHUB_ENABLED`, `GITHUB_CLIENT_ID`, and `GITHUB_CLIENT_SECRET`.
* **Google**: `BETTER_AUTH_GOOGLE_ENABLED`, `GOOGLE_CLIENT_ID`, and `GOOGLE_CLIENT_SECRET`.
* **Local OIDC**: `BETTER_AUTH_OIDC_ENABLED`, optional `BETTER_AUTH_OIDC_PROVIDER_ID`, `BETTER_AUTH_OIDC_DISCOVERY_URL` (or legacy `OIDC_DISCOVERY_URL`), optional `BETTER_AUTH_OIDC_SCOPES`, optional `BETTER_AUTH_OIDC_PKCE`, optional `BETTER_AUTH_OIDC_PROMPT`, plus `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET`.

Non-secret Better Auth settings can also be stored in `systemConfig.auth.betterAuth`, but the `BETTER_AUTH_*` environment variables take precedence over stored config values.

**Endpoints**:
The Better Auth handler is mounted at `${BASE_PATH}${betterAuthConfig.basePath}`. The default `betterAuthConfig.basePath` is `/api/auth/better`; set `BETTER_AUTH_BASE_PATH` to override it at startup, or use `systemConfig.auth.betterAuth.basePath` as a fallback. `BETTER_AUTH_URL` takes precedence over `systemConfig.install.baseUrl` when MCPHub builds redirect URLs. If you also set `BASE_PATH`, prepend it to every example below. 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 is automatically disabled if `DB_URL` is not configured, if `BETTER_AUTH_ENABLED=false`, or if no login providers are effectively enabled with their required credentials.