> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Octop 用户与管理 API：管理账户与设置

管理团队账号、邀请和平台设置。需要「管理用户」权限（管理员默认具备）。

设置页权限和对话是分开的：新账号已经可以和专家聊天，但不能改通道、连接器或知识库，除非你在**管理 → 用户**里授予。页面邀请表单可以预勾这些选项；用 API 创建用户则不会自动授予。

## 用户管理

| 方法     | 路径                                  | 描述                              |
| ------ | ----------------------------------- | ------------------------------- |
| GET    | `/users/permissions`                | 本地化权限目录                         |
| GET    | `/users`                            | 列出所有用户                          |
| POST   | `/users`                            | 创建新用户                           |
| GET    | `/users/{id}`                       | 获取用户详情                          |
| PATCH  | `/users/{id}`                       | 更新角色、显示名、邮箱、启用状态或 `permissions` |
| DELETE | `/users/{id}`                       | 删除用户                            |
| POST   | `/users/{id}/reset-password`        | 重置用户密码                          |
| POST   | `/users/{id}/unlock-login`          | 解除用户登录锁定                        |
| GET    | `/users/invites`                    | 列出邀请                            |
| POST   | `/users/invites`                    | 创建邀请                            |
| POST   | `/users/invites/{invite_id}/revoke` | 撤销待使用邀请                         |

在页面中打开**管理 → 用户**，点击**邀请用户**。把链接发给对方，默认 **7** 天过期（可设 1–90 天）。对方兑换后会得到普通用户账号和默认助手。

也可以用上面的接口创建和撤销邀请。

## 登录与角色

**管理 → 用户**下有这些标签：**用户管理**、**用户分组**、**角色管理**、**飞书登录**、**企微登录**、**钉钉登录**、**通用 OIDC**、**LDAP**。


![用户与 LDAP](/images/ui-ldap.png "用户 → LDAP")

- **角色管理** — 保存权限模板（可细分个性化里的技能、工具、插件、人格、记忆等），邀请时套用
- **用户分组** — 限制谁能使用技能包、知识库、连接器、模型、存储或专家。在资源上把**谁可以使用**设为**指定用户分组**。管理员始终可以访问。
- **LDAP** — 用现有登录表单接入目录账号。关闭自动建号时，先在这里创建**目录账号**。见[认证](/api/authentication.md#ldap-目录登录)
- **OIDC / 飞书 / 钉钉 / 企微** — OAuth 单点登录；读写提供方设置需要 `sso` 权限，路由见[认证](/api/authentication.md)

## 创建用户

```bash
curl -X POST http://127.0.0.1:8088/api/users \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "alice",
    "password": "TempPass123",
    "role": "user",
    "display_name": "Alice Chen",
    "workspace_root_dir": "/data/alice",
    "token_quota": 1000000
  }'
```

成功时返回 `201 Created`。可选 `workspace_root_dir` 限制该用户专家可写入的存储根目录。可选 `token_quota` 限制该账号的 token 用量（创建时即生效）。

## 更新用户

```bash
curl -X PATCH http://127.0.0.1:8088/api/users/5 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"role": "admin", "display_name": "Alice Chen (管理员)"}'
```

可更新字段包括 `role`、`display_name`、`enabled` 和 `locale`。通过设置 `"enabled": false` 可禁用账户，而无需删除。

## 重置密码

```bash
curl -X POST http://127.0.0.1:8088/api/users/5/reset-password \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"new_password": "NewTempPass123"}'
```

返回 `204 No Content`。

## 解除用户锁定

```bash
curl -X POST http://127.0.0.1:8088/api/users/5/unlock-login \
  -H 'Authorization: Bearer <token>'
```


> **说明**
> 
> 连续多次登录失败后（默认阈值由 `OCTOP_LOGIN_MAX_ATTEMPTS` 控制），账户会自动锁定。管理员可以通过此端点在锁定期结束前提前解除锁定。
> 


## 管理员概览

获取平台级汇总信息：

```bash
curl http://127.0.0.1:8088/api/admin/overview \
  -H 'Authorization: Bearer <token>'
```

响应：

```json
{"user_count": 12, "agent_count": 5, "...": "..."}
```

## 审计日志

获取最近的审计日志记录：

```bash
curl http://127.0.0.1:8088/api/admin/audit-log \
  -H 'Authorization: Bearer <token>'
```

## 轮换 JWT 密钥

JWT 密钥轮换仅支持通过 CLI 操作，无法通过 API 进行：

```bash
octop admin rotate-jwt-secret
```


> **注意**
> 
> 轮换 JWT 密钥会立即使**所有**正在进行的会话失效，**包括管理员自己的会话**。轮换后所有人都必须重新登录。
> 

