Smith API：访问策略、数据平面、TTL 与用量治理

这一组是 LangSmith 的控制面。最重要的边界是作用域：Access Policy 和 BYOC Data Plane 使用 Organization 上下文；TTL、用量限制、tenant settings 与大多数个人状态使用 Workspace/Tenant 上下文。即使 API Key、Bearer、Tenant ID、Organization ID 都能出现在鉴权方案里，也不能用一个作用域的 ID 代替另一个作用域的授权。

Access Policy：角色之上的 ABAC

Access Policy 将角色与按资源属性判断的条件连接起来。核心结构是：

AccessPolicy
├── name / description / effect
├── role_ids[]
└── condition_groups[]
    ├── resource_type
    ├── permission
    └── conditions[]
        ├── attribute_name = resource_tag_key
        ├── attribute_key
        ├── attribute_value
        └── operator

当前 OpenAPI 中 attribute_name 只有 resource_tag_key。operator 支持 equals、not_equals、大小写不敏感版本、matches/not_matches，以及相应的 _if_exists 版本。Permission 是严格枚举，覆盖 datasets、projects、runs、prompts、rules、deployments、sandboxes/snapshots、MCP servers、gateway、Fleet、Organization、Workspace 等资源的 read/create/update/delete/manage/invoke/exec 能力。客户端不要自行发明 permission 字符串。

生命周期端点：

操作	路径	语义
create	`POST /api/v1/platform/orgs/current/access-policies`	可同时传 `role_ids` 完成初始绑定，返回新 ID
list/get	collection / `{access_policy_id}`	返回条件、角色关联与时间戳
patch	`{access_policy_id}`	只更新给出的 name、description、effect、condition_groups
delete	`{access_policy_id}`	成功为 204
attach	role 子资源	body 为 `access_policy_ids[]`
detach	role 子资源	IDs 在必填 query 参数中，成功为 204

文档保留了两个同名 attach 路径：.../access-policies/roles/{role_id}/access-policies 与 .../roles/{role_id}/access-policies。新客户端应固定一个经过目标环境验证的 canonical path，不要对两个入口同时写入。Policy 的条件组组合逻辑没有在这些页面中完整形式化，不能在客户端复制一套“看起来相同”的授权判断；最终授权必须由服务端执行。

访问策略变更可能立即造成大面积放权或锁死。生产流程应先读当前 policy 与 role 绑定，保存可回滚快照，做最小差异更新，再用允许/拒绝两类测试身份验证。错误采用 RFC 7807 Problem Details，并增加 remedy；400/403/404/422 都不是可盲目重试的瞬时错误。

BYOC Data Plane

Data Plane 是 Organization 级 BYOC 资源，要求组织已启用 BYOC；创建和删除还要求 org admin。

POST /orgs/current/data-planes 接收 name、region、AWS role_arn、external_id、vpc_cidr 与是否使用 public load balancer。成功返回 202，状态为 requested，不是已经可用。
GET /orgs/current/data-planes 最多返回 50 个，先按状态优先级让 active 靠前，再按最新创建时间排序；响应携带 API URL、状态、更新时间和关联 workspace。
DELETE /orgs/current/data-planes/{id} 先验证已存 AWS role 的删除权限，移除关联 workspace，再异步启动 deprovision；成功仍是 202。Data Plane 非 active 时可能 409。

错误体可能包含 missing_permissions[]，每项给出 AWS action、decision 与 resource ARN，适合生成最小 IAM 修复建议。不要把完整外部角色策略或敏感 AWS 配置写入普通日志。删除会影响关联 workspace，是高风险异步操作：先冻结新绑定，核对关联 workspace，确认 AWS 删除权限，再执行并轮询 status/status_updated_at，不能因为收到 202 就宣布回收完成。

当前用户与 Tenant 设置

/api/v1/me/onboarding_state 记录 tracing、LangGraph Studio、playground、evaluation 和 success view 的完成时间。create/get/update 只需要 Bearer Auth；update 的 path field 只接受文档列出的五个字段。它是产品引导状态，不是能力授权证据。

GET /api/v1/me/ls_user_id 返回当前 LangSmith user ID。GET /me/providers/{providerType} 在当前 tenant 内查询用户对应的外部 provider ID（如 Slack、GitHub），没有绑定时可为 null。外部 provider ID 具有身份关联属性：仅在业务需要时读取，不应把它当跨 tenant 的全局用户主键。

GET /api/v1/settings 返回 tenant ID、display name、created_at 与可空 tenant_handle；POST /api/v1/settings/handle 设置 handle。Handle 通常进入可读 URL 或仓库路径，写入前应做规范化、唯一性和保留字校验，并把 422 当作输入错误处理。

两代 TTL 设置

OpenAPI 同时存在两组 TTL 接口，语义不能简单合并：

API	主要模型	用途
`/workspaces/current/ttl-settings`	`longlived_ttl_days`、`is_custom`、tenant_id	读取/更新当前 workspace 的 long-lived trace 保留天数
`/api/v1/ttl-settings`	`default_trace_tier`、`apply_to_all_projects`、tenant_id	列出或 upsert 默认 trace tier 策略

default_trace_tier 是 longlived 或 shortlived；返回还包含 configured_by=system|user、Organization ID、时间戳以及可能的 longlived_ttl_days。apply_to_all_projects 默认 false。更新 current workspace 时 body 只有 longlived_ttl_days；旧式 upsert 可选择 tenant，并决定是否应用到全部项目。

保留期变更影响成本、合规和可观测性。缩短 TTL 前要确认已有 trace 是否立即受影响、归档/导出是否完成；扩大 TTL 前要估算存储成本与数据最小化要求。接口没有暴露 ETag/版本号，多管理员并发修改时应采用“读当前值 → 比较预期 → 写入 → 回读验证”的控制面流程。

Usage Limits

Usage Limit 支持两种 limit_type：monthly_traces 与 monthly_longlived_traces；scope 为 workspace、project 或 user。请求包含 limit_value，可用 session_id 绑定 project、用 identity_id 绑定 user；传 ID 时是更新既有 limit，否则是创建语义。

GET /api/v1/usage-limits 查看当前 tenant 的限制。
GET /api/v1/usage-limits/org 使用 Organization 上下文查看组织范围配置。
PUT /api/v1/usage-limits 创建或更新。
DELETE /api/v1/usage-limits/{usage_limit_id} 删除，返回 200 object，而不是 204。

scope 与目标字段必须匹配：project 级应绑定 session，user 级应绑定 identity；不要依赖服务端“猜测”作用域。限制是配额控制，不等同于计费账单或安全授权。上线前应测试达到阈值、月度边界、时区、删除限制后的恢复行为，并监控拒绝数和剩余额度。

控制面实施基线

从已认证上下文解析 Organization/Tenant，不接受客户端任意替换作用域 ID。
对 policy、TTL、usage limit 和 data plane 变更保存变更前后值与操作者，但不记录 credential、provider token 或完整外部身份信息。
只有幂等 GET 可以直接做有界退避；202 异步操作转为状态轮询；PATCH/PUT 在超时后先回读，避免重复覆盖。
403 表示功能未启用或权限不足；404 也可能是跨组织隐藏。不要向调用者泄露其他组织资源是否存在。
变更按一个 workspace/role canary 验证，再扩大范围；Access Policy 和默认 TTL/limit 都要准备显式回滚值。