API 接入

本章供需要脚本或其他系统接入的用户阅读；日常使用网页无需创建 API Token。

1. 创建和使用自己的 Token

API Token 是提供给脚本使用的凭据，权限与本人账号相同，应像密码一样保管。

1. 登录网页，在右上角用户菜单打开「API Token」。

2. 新建 Token，填写便于识别用途的名称，选择 30 天至 1 年的有效期，也可选择不过期。

3. 创建后立即复制并安全保存；明文只显示这一次。

4. 脚本请求使用请求头 Authorization: Bearer <API_TOKEN>；不要把 Token 放在 URL、共享文档或代码仓库中。

5. 不再使用时点击「撤销」，立即失效。

使用限制：Token 不能用于创建新的 Token 或修改密码。

泄露后处理：修改密码不会自动撤销已有 Token；需要明确撤销对应 Token。

2. 管理员统一撤销 Token

平台管理员在用户菜单 →「API Token」打开「全部人的」，可查看名称、前缀和最近使用时间，并撤销对应 Token。

员工离职时停用账号，名下 Token 也无法继续使用；新建和撤销 Token 都会留下审计记录。

3. 查看接口文档并验证接入

• 打开接口文档

1. 接口文档默认关闭；由运维在部署配置中设 TIMECHO_API_DOCS_ENABLED=true 并重建服务。

2. 平台管理员访问平台网址下的 /api/v1/docs。

3. 在「Authorize」填入个人 API Token，查看和试调接口。

访问权限：OpenAPI 描述位于 /api/v1/openapi。普通用户和数据库管理员不能访问上述两个文档入口。

• 发送只读请求

管理员只读接入示例，替换域名和 Token 后执行：

curl -fsS https://agent.example.com/api/v1/system/status \
  -H 'Authorization: Bearer <API_TOKEN>'

成功的标志：返回系统自检结果，响应中包含各检查项的状态、级别和说明。

返回状态	优先检查
401	Token 是否完整、过期或撤销，以及账号是否已停用
403	角色、首次改密要求和接口权限

继续集成：按本平台版本的接口文档开发。API Token 不会绕过数据库账号权限、预算和审批规则；批量调用、流式对话或其他接口集成需要进一步支持时，请联系天谋团队。