API Token

API Token 用于让 CueCast 以外的工具访问当前组织中的测试资产和执行能力，适用于：

• CueCast MCP 和 AI Agent。
• CI/CD 流水线中的发布回归。
• 内部脚本或其他自动化平台。
• 查询执行状态和持久化报告。

API Token 代表组织级访问身份，不等同于浏览器登录凭证。每个请求仍会受到 Token 权限、项目范围、有效期以及组织套餐限制的共同约束。

谁可以管理 Token

只有组织 Owner 或 Admin 可以进入「设置 → API Token」创建和撤销 Token。普通成员如需接入 MCP、CI/CD 或脚本，应联系组织管理员创建权限和项目范围合适的 Token，并通过安全渠道交付。

Token 列表展示名称、权限、作用范围、最近使用时间和过期时间，不会再次展示完整明文。

创建 Token

1. 登录 CueCast，进入「设置 → API Token」。
2. 点击「创建 Token」。
3. 填写便于识别使用方的名称，例如「Codex MCP」或「GitHub Actions - 预发」。
4. 选择作用项目、过期日期和权限。
5. 点击「创建」，立即复制并安全保存明文 Token。

Token 明文只展示一次。关闭弹窗后无法重新查看；丢失时需要创建新 Token，并撤销旧 Token。

可选择一个月、三个月、半年、一年、永久或自定义日期。生产和团队共享场景建议设置明确过期时间，并在到期前完成轮换。

项目范围

• 全部项目：Token 可以访问当前组织中已有和后续可见的项目。
• 指定项目：Token 只能读取和执行该项目中的资产。

如果集成只负责一个仓库或环境，优先选择指定项目。即使调用方知道其他项目的 ID，受限 Token 也不能跨项目访问。

权限说明

权限	能力
test:read	读取项目、分组、测试用例和执行计划。
run:create	提交或取消单用例、执行计划和自动录制任务。
run:read	查询 Runner 状态、任务状态和录制进度。
report:read	读取已完成任务的持久化用例或计划报告。

AI Agent 和完整 CI/CD 回归通常需要全部四项权限。只做资产盘点的工具可以仅授予 test:read；只查询现有任务的监控工具可以按需授予 run:read 和 report:read。

权限采用精确匹配，不会因为拥有读取权限而自动获得创建或取消能力。

调用公开 API

国内站公开 API 基础地址为：

https://app.icuecast.com/api/v1

在 HTTP Authorization 请求头中使用 Bearer Token：

curl -H "Authorization: Bearer $CUECAST_API_TOKEN" \
  https://app.icuecast.com/api/v1/projects

不要把真实 Token 直接写入脚本。上例中的 CUECAST_API_TOKEN 应由 CI/CD Secret、密码管理器或本机安全环境变量提供。

提交单用例

curl -X POST \
  -H "Authorization: Bearer $CUECAST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: release-20260916-case-123" \
  -d '{"test_case_id":123,"timeout_seconds":600}' \
  https://app.icuecast.com/api/v1/runs/testcase

提交执行计划

curl -X POST \
  -H "Authorization: Bearer $CUECAST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: release-20260916-plan-45" \
  -d '{"plan_id":45,"timeout_seconds":3600}' \
  https://app.icuecast.com/api/v1/runs/plan

成功提交返回 HTTP 202 和 Run ID。随后可以查询任务和报告：

curl -H "Authorization: Bearer $CUECAST_API_TOKEN" \
  https://app.icuecast.com/api/v1/runs/RUN_ID

curl -H "Authorization: Bearer $CUECAST_API_TOKEN" \
  https://app.icuecast.com/api/v1/runs/RUN_ID/result

报告接口只能在任务进入终态且已生成持久化结果后读取。排队中或执行中的任务会返回“执行尚未结束”。

幂等提交

提交执行或录制请求时，建议提供 Idempotency-Key 请求头，也可以在请求体中传 idempotency_key。

• 同一 Token 使用相同键和相同参数重试，会返回原任务。
• 相同键配合不同参数会返回冲突。
• 每次新的业务执行使用新的键；只有重试同一次不确定提交时才复用原键。

这可以避免调用方在网络超时后重复创建任务，从而重复操作真实业务数据。

与 MCP 和 Runner 的关系

MCP 在用户级配置中保存 API 地址和 Token，通过公开 API 查询资产、提交任务并读取结果。真正的浏览器回放由同组织的在线 Chrome 扩展 Runner 完成；Token 本身不会启动浏览器，也不会绕过 Runner 在线检查。

单用例默认超时 600 秒；执行计划默认由整个计划共用 3600 秒。详细接入、超时和 Runner 限制见 AI Agent、MCP 与 Runner。

由 Token 发起的任务会出现在执行历史中，并根据调用方式标记为 MCP 或 API 来源。

轮换和撤销

CueCast 不支持重新查看或修改现有 Token 的明文。轮换方式：

1. 创建权限和项目范围相同的新 Token。
2. 更新 MCP、CI/CD Secret 或脚本配置。
3. 验证新 Token 可以查询项目并完成预期操作。
4. 回到 Token 列表撤销旧 Token。

撤销后，使用旧 Token 的 MCP、CI/CD、脚本或外部系统会立即失效。撤销不会删除此前生成的执行记录和报告。

安全建议

• 每个集成和环境使用独立 Token，名称中写明用途。
• 使用最小权限和尽可能小的项目范围。
• 优先设置有效期，并在人员或系统责任变化时及时轮换。
• 把 Token 放在 Secret 管理系统或用户级 MCP 配置中。
• 不要提交到 Git、写入网页前端、记录到日志或粘贴到工单和公开对话。
• 怀疑泄露时先撤销，再创建替代 Token；不要等待调查完成后才停用。
• 定期检查「最近使用」时间，撤销长期不用的 Token。

常见错误

现象	处理方式
未认证或 Token 无效	检查 Bearer 格式、Token 是否复制完整、是否过期或已撤销。
权限不足	补充接口要求的权限，或创建用途更合适的新 Token。
无权访问项目	检查 Token 的指定项目范围，以及请求中的项目、用例或计划 ID。
没有可用 Runner	打开 Chrome 和扩展，登录同一组织的 CueCast 页面。
报告尚不可用	先使用 Run ID 查询状态，等待任务进入终态并保存结果。
配额不足	检查当前组织的订阅和执行额度。