工作区 API 概览
工作区 (Workspace) 是你作为服务商 (SP / 合作方) 拥有的一个成员与计费边界：你自己的用户在这里成为「成员」，拿着你签发的短时令牌去和 Agent 对话。 工作区 API 就是你的后端管理这个边界用的接口——开通成员、签发会话、发放积分、读取 Agent。
这是服务端到服务端的集成能力，面向把 OpenHex Agent 接进自己产品（网站、小程序、App）的合作方。只是自己写脚本和 Agent 对话，用个人 API Key 就够了，见鉴权。
什么时候需要它
| 你的场景 | 需要工作区 API 吗 |
|---|---|
| 在自己的网站上挂一个客服气泡，访客不用登录 | ✅ 需要，给每个访客签发会话令牌 |
| 把 Agent 接进你的小程序 / App，用户用你的账号体系登录 | ✅ 需要，按你的用户 id 开通成员 |
| 给你的用户发放积分，让他们为自己的对话付费 | ✅ 需要 |
| 用脚本或后端任务调用自己的 Agent | ❌ 用个人 API Key 即可 |
| 以所有者身份训练自己的 Agent | ❌ 用个人 API Key，见训练模式 |
一个完整的流程
你的后端（持有工作区 API Key）
┌──────────────────────────────────────────┐
你的用户登录 ───────▶│ startVisitorSession({ sp_user_ref }) │
│ = provisionMember + mintSession │
└──────────────────────┬───────────────────┘
│ 会话令牌（短时）
▼
你的客户端 <ChatWidget getToken /> 或 OpenhexClient
│
▼
OpenHex Agent（费用默认记在 Agent 所有者）
第 1 步：准备工作区和工作区 API Key
工作区 API Key 形如 sk_ 加 64 位十六进制字符，只对一个工作区有效。目前通过接口签发，用的是你的个人 API Key（在 app.openhex.tech 的 设置 → API Key 创建，形如 mysta_…）。
① 查看你名下的工作区，拿到 slug：
curl https://api.openhex.tech/api/v2/workspaces \
-H "Authorization: Bearer mysta_..."
# → { "workspaces": [ { "id": "…", "slug": "your-workspace", "display_name": "…", "status": "active", … } ] }
② 列表为空就先创建一个。 slug 为 3–64 位，只能包含小写字母、数字和中划线，且不能以中划线开头或结尾：
curl -X POST https://api.openhex.tech/api/v2/workspaces \
-H "Authorization: Bearer mysta_..." -H "Content-Type: application/json" \
-d '{"slug":"your-workspace","display_name":"你的团队"}'
# slug 已被占用时返回 409 slug already taken
③ 在工作区上签发 API Key：
curl -X POST https://api.openhex.tech/api/v2/workspaces/your-workspace/api-keys \
-H "Authorization: Bearer mysta_..." -H "Content-Type: application/json" \
-d '{"label":"web-backend"}'
# → 201 { "id": "…", "label": "web-backend", "created_at": "…", "token": "sk_…" }
token 只在这一次完整返回，平台只保存哈希。立刻存进后端的环境变量（例如 OPENHEX_WORKSPACE_KEY），丢了只能吊销后重新签发。
管理已有的 Key：
# 列出（不含明文）
curl https://api.openhex.tech/api/v2/workspaces/your-workspace/api-keys \
-H "Authorization: Bearer mysta_..."
# → { "keys": [ { "id", "label", "last_used_at", "revoked_at", "created_at" } ] }
# 吊销
curl -X DELETE https://api.openhex.tech/api/v2/workspaces/your-workspace/api-keys/<id> \
-H "Authorization: Bearer mysta_..."
# → 204；此后用这把 Key 调用会得到 403 API key revoked
⚠️ 工作区 API Key 和个人 API Key 都是后端密钥，绝不能进入浏览器、小程序包或 App 安装包。客户端只拿会话令牌。
第 2 步：在后端创建客户端
import { OpenhexClient } from '@openhex-ai/agent-sdk';
const client = new OpenhexClient({ apiKey: process.env.OPENHEX_WORKSPACE_KEY! });
// 不确定这把 Key 属于哪个工作区？问一次
const me = await client.workspaces.whoami();
// → { workspace_id, slug, display_name, status, api_key_id }
// 绑定 slug，之后的调用都不用再传
const ws = client.workspace(me.slug);
whoami 是唯一不需要 slug 的方法：工作区是从 Key 反查出来的，所以它不会答错。其他方法的 slug 起校验作用——必须和 Key 所属的工作区一致，否则返回 403 API key does not match workspace。查一次、写进环境变量即可，不必每个请求都调。
每个方法也有带 slug 参数的等价形式：client.workspaces.listMembers(slug) 等同于 client.workspace(slug).listMembers()。
第 3 步：为用户签发令牌
const { token, expires_at } = await ws.startVisitorSession({
sp_user_ref: `user_${yourUserId}`,
ttl_seconds: 1800,
});
// 把 token 交给客户端
之后客户端就能用这个令牌和 Agent 对话了。详见会话令牌。
能力一览
| 能力 | 方法 | 页面 |
|---|---|---|
| 确认 Key 所属工作区 | whoami | 本页 |
| 开通、列出、停用成员 | provisionMember / listMembers / suspendMember | 成员 |
| 签发会话令牌、公开短信注册 | startVisitorSession / mintSession / sendSmsCode / verifySmsCode | 会话令牌 |
| 发放积分 | grantCredits | 积分 |
| 读取工作区里的 Agent | listAgents / getAgent | 读取 Agent |
每个方法接受哪种凭据、对应哪个 HTTP 路由、会返回哪些错误，见方法参考；字段级的 REST 文档与在线调试见 Workspace API REST 参考。
费用由谁承担
成员和 Agent 对话产生的费用，默认记在 Agent 所有者头上：成员余额为 0 也能正常聊天，网站客服这类匿名场景不需要发积分。只有 Agent 所有者把计费方设为「由使用者付费」时，才需要通过积分给成员充值。
不在工作区 API 里的能力
- 工作区账本、用量洞察、单成员账本：服务商管理后台的职责，不属于合作方接口。
- 修改工作区设置（例如开启公开短信注册）：不在公开接口中。