Smith API：SCIM Tokens、Service Accounts 与 Tenant 兼容层

这三组都服务于自动化身份/层级，但对象不同：SCIM token 供外部身份目录 provisioning；service account 是 organization 内的非人类执行主体；旧语义中的 tenant 基本对应 workspace，但 create tenant 还可能同时创建 organization。

SCIM bearer token 生命周期

端点都在 /api/v1/platform/orgs/current/scim/tokens：

操作	方法	返回 secret?	权限
Create	POST	完整 `token` 仅 201 创建响应一次	OrganizationManage
List	GET	否，只含 ID/short token/description/timestamps	OrganizationRead
Get	GET `/{id}`	否	OrganizationRead
Update	PATCH `/{id}`	只改 description	OrganizationManage
Delete	DELETE `/{id}`	204	OrganizationManage

响应还含 last_used_at，轮换/清理前可判断是否仍在使用，但这个时间不能证明某 SCIM client 已完全切换。轮换流程应先新建并立即保存 token、在 IdP 更新、验证 provisioning、观察旧 token last-used 再删除。

SCIM secret 不可通过 get/list 恢复。创建响应丢失只能新建；不要把 token 放进 Terraform state 明文、CI log 或工单。API 明确有 401、403、404、500、503，自动化对 503 有界重试，对 403 不重试，对 create 超时先 list 检查。

Service accounts

POST /api/v1/service-accounts 创建非人类主体：name 必填，可带 workspace assignments；响应含 service account ID、organization ID、default workspace ID 和 organization identity ID。GET 列 current organization 所有 service accounts，DELETE /{service_account_id} 删除。

Service account 本身不是 secret；要执行 API 通常仍需为它配置受控 key/role。设计原则：

一个 workload/环境一个 account，不跨 dev/prod 复用；
workspace assignment 与 default workspace 显式设置，避免落入错误租户；
先禁用/撤销 keys 与任务，再删除 account；
owner、用途、到期/复核日期写 metadata 或 CMDB；
监控 account 的 key 使用而不是只监控 human PAT。

Tenant endpoints 与 workspace 语义

POST /api/v1/tenants 的描述是“创建一个新 organization 及对应 workspace”。Request 可指定 UUID、organization ID、display name、handle、personal；display name 的允许字符与新 workspace endpoint 不完全相同。响应 Tenant 含 organization ID、created time、deleted flag、handle 与 data-plane URL。

GET /api/v1/tenants 列当前 Bearer 可见 tenants，include_deleted=false、skip_create=false 默认；响应额外带 read-only、role、permissions。

新代码优先使用明确的 Organizations/Workspaces endpoints，除非现有 SDK/部署仍要求 tenant API。不要把 tenant ID、workspace ID、organization ID 混成一个字段：OpenAPI 中 workspace-scoped security 仍叫 Tenant ID，而控制面 API 使用 organization ID。

自动化安全边界

flowchart LR
    A["Human admin / IdP"] --> B["SCIM token"]
    B --> C["User/group provisioning"]
    D["CI / Service workload"] --> E["Service account + scoped key"]
    E --> F["Assigned workspaces"]
    G["Control plane"] --> H["Organization"]
    H --> I["Workspace / legacy Tenant"]

SCIM token 只能做 provisioning 所需 scope，不替代 LangSmith API key。
Service account key 不应拥有组织管理权限，除非 workload 就是组织控制面。
创建 tenant 可能扩大组织/账单边界，禁止用作“找不到 workspace 就自动创建”的普通 fallback。
删除任一主体前先撤销所有 token/key、停作业、导出审计并验证没有 orphan ownership。