API 参考 / api-tokens

创建项目 API Token

POST /api/v1/projects/{projectId}/api-tokens · createAPIToken

为当前用户和当前项目创建一个 PAT。响应只在本次创建时包含 plainToken；服务端只存 sha256 hash。

scopeMode=all 表示 token scope 为当前全部治理权限键（截至本版本共 8 项： view_project / manage_project_settings / manage_project_members / manage_project_roles / manage_acceptance_config / run_acceptance / view_audit / manage_workflows， 即后端 roles.AllPermissionKeys），实际权限仍与用户实时项目角色取交集—— token 拿到的是天花板，不是快照。

这里刻意不再把数字写死在别处（B-00314）：此前弹窗写 13 项、本描述写 12 项、后端实际 8 项， 三处互不相同——13 与 12 都是权限字典退场（manage_requirements / manage_work_items / manage_schedule / manage_bugs 随 migration 20260723090018 退场、manage_documents 随 20260729090021 退场）之前的历史数字，没跟着改。真值只有一处：roles.AllPermissionKeys。

scopeMode=read_only 表示只读哨兵，GET 允许、写命令拒绝。PAT 不可调用本端点。

本接口要求浏览器会话。Bearer API Token 无法调用——Token 的生命周期管理必须在网页端完成。

参数

projectId（必填）
string

请求体

name（必填）
string
scopeMode（必填）
enum；取值：all / read_only
expiresInDays（必填）
integer —— 有效期天数；7/30/90 为推荐项，自定义传正整数，0 表示不过期。

响应字段 · 201

token（必填）
APIToken
token.id（必填）
string
token.userId（必填）
string
token.projectId（必填）
string
token.name（必填）
string
token.tokenPrefix（必填）
string
token.scopes（必填）
string[]
token.expiresAt
string
token.lastUsedAt
string
token.revokedAt
string
token.createdAt（必填）
string
plainToken（必填）
string —— PAT 明文（wfp_ 前缀），只在创建响应出现一次。

错误

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/projects/{projectId}/api-tokens" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"name":"示例标题","scopeMode":"all","expiresInDays":1}'

响应示例

HTTP/1.1 201
{
  "token": {
    "id": "018f3c2e-0000-7000-8000-000000000000",
    "userId": "018f3c2e-0000-7000-8000-000000000000",
    "projectId": "018f3c2e-0000-7000-8000-000000000000",
    "name": "示例标题",
    "tokenPrefix": "示例文本",
    "scopes": [
      "read_only"
    ],
    "createdAt": "示例文本"
  },
  "plainToken": "示例文本"
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引

Workflow 正在加载…