Smith API：Workspace 成员、Secrets、标签、共享与生命周期

Workspace（部分 schema/headers 仍叫 tenant）是日常数据、项目、prompt、Agent 和权限的工作边界。创建/list/get 通过 Organization 上下文；/workspaces/current/* 则依赖 Tenant ID/API key 的当前 workspace 上下文。服务端不能让 path/header 的两个 workspace 标识不一致。

Workspace CRUD

操作	方法与路径	边界
Create	`POST /api/v1/workspaces`	Organization context；name 必填，可给 UUID/handle
List	`GET /api/v1/workspaces`	current org；include_deleted、data_plane_id
Get	`GET /api/v1/workspaces/{id}`	current org + identity scoped；可 include deleted/data plane
Patch	`PATCH /api/v1/workspaces/{id}`	当前 schema 要完整 display_name
Delete	`DELETE /api/v1/workspaces/{id}`	Tenant-scoped security，属于高风险删除

Display name 允许字母数字、空格及 - _ ' @ ( )。Get/List 返回 TenantForUser：ID、organization、created time、display name、personal/deleted、handle、data-plane URL、read-only、role 与 permissions。

删除前要盘点 datasets、projects、prompts、deployments、Fleet Agents、secrets、shared tokens、exports 与合规保留。API 成功不代表外部系统、缓存和数据 plane 已完全清理，需异步状态/审计复核。

Workspace 成员与邀请

已有 organization member 可 POST /workspaces/current/members 加入，request 支持 user/org identity/LS user、read-only 与 role。批量 endpoint 最多 500，可把用户同时邀请到 workspace 和 organization，所以 security 同时接受 Tenant 与 Organization 上下文。

Active/pending members 支持 limit 1–500、offset、email/name 查询、user IDs、disabled 与排序。Workspace combined list 返回 members + pending；claim/delete pending invite 使用登录 Bearer，pending/active Patch 分别改 role。

read_only 与 role ID 同时存在，不能只检查一个字段；真实权限应以返回 permissions/服务端授权为准。批量 invite 用 email 幂等，记录每项结果；删除成员前转移 resource ownership。

Workspace Secrets

端点	返回内容
`GET /workspaces/current/secrets`	只列 `key` 名称，不返回 value
`POST /workspaces/current/secrets`	数组 upsert `{key, value\|null}`
`GET .../secrets/encrypted`	给 Fleet/Polly 等服务的加密 blob，可选 key names

Encrypted endpoint 的 service 只允许 agent_builder 或 polly；expand_iam_role=true 可把 AWS_IAM_ROLE_ARN 展开为临时 STS credentials，风险高、必须最小 IAM trust/policy、短期和审计。

value=null 的 upsert 删除/清空语义需在 staging 通过真实 API 验证，不能凭 schema 猜测。List 只返回 key 是正确防泄漏设计；接收 encrypted blob 的内部服务仍须认证、绑定 tenant、禁止日志输出与跨环境复用。

Tags 三层模型

Workspace tagging 分为：

TagKey：key 1–255 字符、可有 description；
TagValue：属于 key，value 1–255 字符；
Tagging：把 tag value 绑定 {resource_type, resource_id}。

三层都有 create/list/get/update/delete；还能：

列全部 key + values；
按 resource type 列 tags；
查单 resource；
POST 一组 resource IDs 批量查；
按 tag value 列 taggings；
workspace stats 用一组 tag value IDs 过滤。

删除 key/value 可能级联影响 taggings，文档未在端点摘要保证具体级联语义，上线前实测。Tags 适合分类/成本/搜索，不是授权边界；resource_type 与 resource_id 必须服务端验证属于 current workspace。

Shared tokens

GET /workspaces/current/shared 分页列 workspace 共享的 run/dataset entities 和 token；DELETE 接收 share_tokens 或 unshare_all 批量撤销。Share token 是“持有即可访问”的能力凭证，不能记录在 analytics、URL referrer 或日志。

unshare_all=true 属于组织级事故处置或策略变更，执行前导出清单、通知 owner、双人审批并准备业务回滚。删除单项使用 token 值时也要防止请求/错误日志泄漏。

Stats 与 usage limit

Stats 返回当前 workspace 的 dataset、project/tracer session、repo、annotation queue、deployment、dashboard、evaluator、custom app counts，可按 tag value IDs 过滤。它是控制面统计，不保证与异步 data plane 强一致，不用作财务或删除完成的唯一证明。

Usage limit info 返回 in_reject_set、limit type 与 tenant limit。进入 reject set 后新请求可能被拒；客户端应在写入前做监控，但仍以服务端拒绝为最终权威，不依赖缓存值抢跑。

生产基线

Organization ID 与 Tenant ID 从可信 credential/session 得出，path/header/body 全部交叉校验。
Workspace create 使用稳定幂等 ID；不要“list 空就 create”造成重复组织/空间。
Secrets 永不回显；key 名也可能泄露架构信息，限制 list 权限。
Tag update/delete 做引用检查；标签不参与 security decision。
Shared token 建立过期、撤销、扫描和泄漏应急；默认禁止 public sharing。
Delete workspace 使用变更单、完整导出、依赖检查、两人批准和删除后审计。