接入指南

Workspace OpenAPI 面向服务端自动化。每把 OpenAPI Key 固定绑定一个工作区，按所选权限执行操作；请求不能通过 workspace_id 切换工作区。

它使用独立的入口和 Bearer 密钥。模型调用使用的 sk-apigo-... API Key 不能用于这里；OpenAPI Key 也不能用于模型推理、控制台登录或管理其他 OpenAPI Key。模型接入见 API 密钥。

创建与获取密钥

1. 在控制台切换到目标工作区，打开 管理与审计 → OpenAPI 密钥。
2. 工作区 owner 或 admin 点击创建，填写名称、到期时间并选择必要权限。只读接入可先选择 workspace:read 和 usage:read。
3. 企业空间可配置密钥查看成员；创建者自动获得查看授权。个人空间不展示成员授权和成员管理权限。
4. 由获得查看授权的有效成员显示并复制密钥，保存到服务端密钥管理系统。

操作权限决定机器能做什么；密钥查看成员决定谁能取得明文。管理权限不自动授予明文查看权。移除查看成员不会使其已经复制的密钥失效；如需切断访问，请轮换、停用或撤销密钥。轮换后更新使用该密钥的服务。

服务地址与鉴权

从部署管理员获取 Workspace OpenAPI 的独立根地址，设置为 OPENAPI_BASE_URL，末尾不要带 /v1。不要使用模型网关的 Base URL。生产接入应使用部署提供的 HTTPS 域名。

独立监听端口为当前部署配置的 18891，可通过 PLATFORM_SERVER_OPENAPI_HTTP_ADDR 调整；监听地址为空时不启用。外部网关使用自己的 HTTP/HTTPS 端口，无需在域名后加 :18891。

本地 Kubernetes 已配置的入口为：

export OPENAPI_BASE_URL='http://openapi.localhost'
# OPENAPI_KEY 从密钥管理系统注入，不要写入仓库或前端代码。
curl --fail-with-body "$OPENAPI_BASE_URL/v1/workspace" \
  -H "Authorization: Bearer $OPENAPI_KEY"

仅需直连本地 Kubernetes Service 时，可运行以下命令，并在另一个终端使用 http://127.0.0.1:18891。Service 端口不会自动映射到宿主机。

kubectl --context orbstack -n tidemind port-forward svc/platform-openapi 18891:18891

独立服务的 GET /openapi.json 提供完整请求、响应和 x-scope 定义，可导入支持 OpenAPI 的客户端：

curl --fail-with-body "$OPENAPI_BASE_URL/openapi.json" -o workspace-openapi.json

接口与权限

权限使用下表中的精确名称，不支持 *。所有路径相对于独立根地址；{id} 使用接口返回的外部 ID。

成员邀请请求使用 email 和可选的 name，不接受角色提升；移除操作不能作用于 owner、admin 或 manager。邀请响应中的 email_queued 表示邮件已排队，不表示已投递。

查询用量与账单

用量必须指定 range，支持 1h、1d、7d、30d、month、custom。custom 必须同时提供 from、to，最多 30 天。

curl --fail-with-body "$OPENAPI_BASE_URL/v1/usage?range=7d" \
  -H "Authorization: Bearer $OPENAPI_KEY"

curl --fail-with-body "$OPENAPI_BASE_URL/v1/bills?page=1&page_size=20" \
  -H "Authorization: Bearer $OPENAPI_KEY"

账单还支持 type、from、to 筛选。时间支持 RFC3339，或按 UTC 解析的 YYYY-MM-DD 日期；RFC3339 的 to 不包含该时刻，日期形式的 to 包含该日。

Key、账单和成员列表使用 page / page_size，默认第 1 页、每页 20 条，最多 100 条。响应位于 data，分页字段为 items、total、page、page_size；用量接口不使用该分页结构。

写操作与重试

所有写操作都必须携带 Idempotency-Key，长度为 1–200 字节。每次新的业务操作生成独立请求号；网络重试时保留原请求号和请求内容。同一机器 Key、同一操作、同一请求号重复提交相同参数会复用结果，更换参数返回 409。不要在每次重试时生成新请求号。

下面修改一个已有模型调用 Key 的 RPM；先将 MODEL_KEY_ID 设置为列表返回的真实 ID，将 REQUEST_ID 设置为本次操作的唯一请求号。

curl --fail-with-body -X PATCH "$OPENAPI_BASE_URL/v1/api-keys/$MODEL_KEY_ID" \
  -H "Authorization: Bearer $OPENAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H 'Content-Type: application/json' \
  --data '{"limits":{"rpm_limit":60}}'

更新请求只支持 limits。省略限额保留原值；美元限额 day_limit_usd、d7_limit_usd、d30_limit_usd 最多两位小数，显式 null 清除对应限额，且日额度 ≤ 7 日额度 ≤ 30 日额度。运行时字段 rpm_limit、tpm_limit、concurrency_limit 的 0 / null 仍受工作区硬上限约束，见 限额与请求准入。

创建模型调用 Key 使用 name、当前工作区有效成员的 member_id、billing_type: "credit_balance"，以及可选的 limits。企业可从成员接口取得成员 ID。创建响应包含 data.key 与本次新 Key 的 data.full_secret；同请求的幂等重放可恢复本次创建结果，普通列表和更新不会返回明文。

响应与错误

JSON 响应使用 { "code": 0, "message": "ok", "data": ... }，code: 0 表示成功。客户端同时检查 HTTP 状态和业务 code，不要只判断是否收到 JSON。

不要记录 Authorization 或密钥明文。排查问题时保留脱敏后的 HTTP 状态、业务错误码与操作路径；写请求重试继续使用原幂等请求号。