---
title: "Authentication"
description: "Manage users and authentication."
---

import { Card, Cards } from 'mintlify';

<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
  {
    "username": "admin",
    "password": "your-admin-password"
  }
  ```
- **Success Response**:
  ```json
  {
    "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
  {
    "username": "newuser",
    "password": "password123",
    "isAdmin": false
  }
  ```
- **Success Response**:
  ```json
  {
    "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
  {
    "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
  {
    "currentPassword": "oldpassword",
    "newPassword": "newpassword123"
  }
  ```
- **Success Response**:
  ```json
  {
    "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.
