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

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

> 使用 Octop 的 /api/users 和 /api/admin 端点管理用户账户、角色、审计日志以及平台设置（仅限管理员）。

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

设置页权限和对话是分开的：新账号已经可以和专家聊天，但不能改通道、连接器或知识库，除非你在**管理 → 用户**里授予。页面邀请表单可以预勾这些选项；用 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 天）。对方兑换后会得到普通用户账号和默认助手。

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

## 创建用户

```bash theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
curl -X POST http://127.0.0.1:8088/api/users/5/unlock-login \
  -H 'Authorization: Bearer <token>'
```

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

## 管理员概览

获取平台级汇总信息：

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

响应：

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

## 审计日志

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

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

## 轮换 JWT 密钥

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

```bash theme={null}
octop admin rotate-jwt-secret
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.