--- type: study created: 2026-08-11 updated: 2026-08-11 sensitivity: standard status: verified tags: - study - langchain - langsmith - smith-api - authorization - governance topic: LangSmith Smith API 访问策略、BYOC 数据平面、身份设置、TTL 与用量治理 sources: - https://docs.langchain.com/langsmith/smith-api/access_policies/attach-access-policies-to-a-role - https://docs.langchain.com/langsmith/smith-api/access_policies/attach-access-policies-to-a-role-1 - https://docs.langchain.com/langsmith/smith-api/access_policies/create-an-access-policy - https://docs.langchain.com/langsmith/smith-api/access_policies/delete-an-access-policy - https://docs.langchain.com/langsmith/smith-api/access_policies/detach-access-policies-from-a-role - https://docs.langchain.com/langsmith/smith-api/access_policies/get-an-access-policy - https://docs.langchain.com/langsmith/smith-api/access_policies/list-access-policies - https://docs.langchain.com/langsmith/smith-api/access_policies/update-an-access-policy - https://docs.langchain.com/langsmith/smith-api/data_planes/create-a-new-data-plane - https://docs.langchain.com/langsmith/smith-api/data_planes/delete-a-data-plane - https://docs.langchain.com/langsmith/smith-api/data_planes/list-data-planes-for-the-current-organization - https://docs.langchain.com/langsmith/smith-api/me/create-onboarding-state - https://docs.langchain.com/langsmith/smith-api/me/get-ls-user-id - https://docs.langchain.com/langsmith/smith-api/me/get-onboarding-state - https://docs.langchain.com/langsmith/smith-api/me/get-the-authenticated-users-provider-user-id - https://docs.langchain.com/langsmith/smith-api/me/update-onboarding-state-field - https://docs.langchain.com/langsmith/smith-api/settings/get-settings - https://docs.langchain.com/langsmith/smith-api/settings/set-tenant-handle - https://docs.langchain.com/langsmith/smith-api/ttl-settings/get-workspace-ttl-settings - https://docs.langchain.com/langsmith/smith-api/ttl-settings/list-ttl-settings - https://docs.langchain.com/langsmith/smith-api/ttl-settings/update-workspace-ttl-settings - https://docs.langchain.com/langsmith/smith-api/ttl-settings/upsert-ttl-settings - https://docs.langchain.com/langsmith/smith-api/usage-limits/delete-usage-limit - https://docs.langchain.com/langsmith/smith-api/usage-limits/list-org-usage-limits - https://docs.langchain.com/langsmith/smith-api/usage-limits/list-usage-limits - https://docs.langchain.com/langsmith/smith-api/usage-limits/upsert-usage-limit last_verified: 2026-08-11 --- # 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 将角色与按资源属性判断的条件连接起来。核心结构是： ```text 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；不要依赖服务端“猜测”作用域。限制是配额控制，不等同于计费账单或安全授权。上线前应测试达到阈值、月度边界、时区、删除限制后的恢复行为，并监控拒绝数和剩余额度。 ## 控制面实施基线 1. 从已认证上下文解析 Organization/Tenant，不接受客户端任意替换作用域 ID。 2. 对 policy、TTL、usage limit 和 data plane 变更保存变更前后值与操作者，但不记录 credential、provider token 或完整外部身份信息。 3. 只有幂等 GET 可以直接做有界退避；202 异步操作转为状态轮询；PATCH/PUT 在超时后先回读，避免重复覆盖。 4. 403 表示功能未启用或权限不足；404 也可能是跨组织隐藏。不要向调用者泄露其他组织资源是否存在。 5. 变更按一个 workspace/role canary 验证，再扩大范围；Access Policy 和默认 TTL/limit 都要准备显式回滚值。