> ## 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.

# 身份验证

> 管理用户和身份验证。

<Card title="POST /api/auth/login" href="#login">
  登录以获取 JWT 令牌。
</Card>

<Card title="POST /api/auth/register" href="#register">
  注册一个新用户。
</Card>

<Card title="GET /api/auth/user" href="#get-current-user">
  获取当前已验证的用户。
</Card>

<Card title="POST /api/auth/change-password" href="#change-password">
  更改当前用户的密码。
</Card>

***

### 登录

验证用户身份并返回 JWT 令牌及用户详细信息。

* **端点**: `/api/auth/login`
* **方法**: `POST`
* **正文**:
  * `username` (string, 必填): 用户名。
  * `password` (string, 必填): 用户密码。
* **请求示例**:
  ```json theme={null}
  {
    "username": "admin",
    "password": "your-admin-password"
  }
  ```
* **成功响应**:
  ```json theme={null}
  {
    "success": true,
    "message": "登录成功",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "admin",
      "isAdmin": true,
      "permissions": { ... }
    }
  }
  ```

***

### 注册

注册一个新用户并返回 JWT 令牌。

* **端点**: `/api/auth/register`
* **方法**: `POST`
* **正文**:
  * `username` (string, 必填): 新的用户名。
  * `password` (string, 必填): 新的用户密码 (至少6个字符)。
  * `isAdmin` (boolean, 可选): 用户是否应有管理员权限。
* **请求示例**:
  ```json theme={null}
  {
    "username": "newuser",
    "password": "password123",
    "isAdmin": false
  }
  ```
* **成功响应**:
  ```json theme={null}
  {
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "newuser",
      "isAdmin": false,
      "permissions": { ... }
    }
  }
  ```

***

### 获取当前用户

检索当前通过身份验证的用户的个人资料。

* **端点**: `/api/auth/user`
* **方法**: `GET`
* **身份验证**: 需要承载令牌 (Bearer Token)。
* **成功响应**:
  ```json theme={null}
  {
    "success": true,
    "user": {
      "username": "admin",
      "isAdmin": true,
      "permissions": { ... }
    }
  }
  ```

***

### 更改密码

允许通过身份验证的用户更改其密码。

* **端点**: `/api/auth/change-password`
* **方法**: `POST`
* **身份验证**: 需要承载令牌 (Bearer Token)。
* **正文**:
  * `currentPassword` (string, 必填): 用户的当前密码。
  * `newPassword` (string, 必填): 新的密码 (至少6个字符)。
* **请求示例**:
  ```json theme={null}
  {
    "currentPassword": "oldpassword",
    "newPassword": "newpassword123"
  }
  ```
* **成功响应**:
  ```json theme={null}
  {
    "success": true,
    "message": "密码更新成功"
  }
  ```

***

### 社交登录 (Better Auth)

MCPHub 通过集成 [Better Auth](https://www.better-auth.com/) 支持社交登录功能（GitHub, Google 等）。

**前提条件**:

1. **数据库模式**: 必须配置 `DB_URL` 环境变量（Better Auth 需要 PostgreSQL 进行数据持久化）。
2. **启动配置**: Better Auth 相关设置只会在启动时读取一次，因此改完后需要重启 MCPHub。
3. **环境变量**:

* **全局**: `BETTER_AUTH_ENABLED`、`BETTER_AUTH_URL`、可选 `BETTER_AUTH_BASE_PATH`、可选 `BETTER_AUTH_TRUSTED_ORIGINS`。
* **GitHub**: `BETTER_AUTH_GITHUB_ENABLED`、`GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET`。
* **Google**: `BETTER_AUTH_GOOGLE_ENABLED`、`GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET`。
* **本地 OIDC**: `BETTER_AUTH_OIDC_ENABLED`、可选 `BETTER_AUTH_OIDC_PROVIDER_ID`、`BETTER_AUTH_OIDC_DISCOVERY_URL`（或兼容别名 `OIDC_DISCOVERY_URL`）、可选 `BETTER_AUTH_OIDC_SCOPES`、可选 `BETTER_AUTH_OIDC_PKCE`、可选 `BETTER_AUTH_OIDC_PROMPT`，以及 `OIDC_CLIENT_ID`、`OIDC_CLIENT_SECRET`。

非敏感的 Better Auth 配置也可以保存在 `systemConfig.auth.betterAuth` 中，但 `BETTER_AUTH_*` 环境变量会优先覆盖它们。

**端点**:
Better Auth API 挂载在 `${BASE_PATH}${betterAuthConfig.basePath}`。默认路径是 `/api/auth/better`；可以用 `BETTER_AUTH_BASE_PATH` 在启动时覆盖，也可以把 `systemConfig.auth.betterAuth.basePath` 作为后备值。构建回调 URL 时，`BETTER_AUTH_URL` 会优先于 `systemConfig.install.baseUrl` 生效。主要端点包括：

* **发起登录**:
  * `GET /api/auth/better/signIn/social?provider=github`
  * `GET /api/auth/better/signIn/social?provider=google`

* **会话管理**:
  * `GET /api/auth/better/session` (获取当前会话)
  * `POST /api/auth/better/signOut` (登出)

如需完整的端点列表和使用详情，请参阅 [Better Auth API 文档](https://www.better-auth.com/docs)。

**禁用 Better Auth**:

如果未配置 `DB_URL`、设置了 `BETTER_AUTH_ENABLED=false`，或者没有任何提供商在满足凭据条件后真正启用，Better Auth 都会自动禁用。