---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - workspace
  - secrets
  - tags
topic: LangSmith Smith API Workspace 成员、Secrets、标签、共享与生命周期
sources:
  - https://docs.langchain.com/langsmith/smith-api/workspaces/add-member-to-current-workspace
  - https://docs.langchain.com/langsmith/smith-api/workspaces/add-members-to-current-workspace-batch
  - https://docs.langchain.com/langsmith/smith-api/workspaces/bulk-unshare-entities
  - https://docs.langchain.com/langsmith/smith-api/workspaces/claim-pending-workspace-invite
  - https://docs.langchain.com/langsmith/smith-api/workspaces/create-tag-key
  - https://docs.langchain.com/langsmith/smith-api/workspaces/create-tag-value
  - https://docs.langchain.com/langsmith/smith-api/workspaces/create-tagging
  - https://docs.langchain.com/langsmith/smith-api/workspaces/create-workspace
  - https://docs.langchain.com/langsmith/smith-api/workspaces/delete-current-workspace-member
  - https://docs.langchain.com/langsmith/smith-api/workspaces/delete-current-workspace-pending-member
  - https://docs.langchain.com/langsmith/smith-api/workspaces/delete-pending-workspace-invite
  - https://docs.langchain.com/langsmith/smith-api/workspaces/delete-tag-key
  - https://docs.langchain.com/langsmith/smith-api/workspaces/delete-tag-value
  - https://docs.langchain.com/langsmith/smith-api/workspaces/delete-tagging
  - https://docs.langchain.com/langsmith/smith-api/workspaces/delete-workspace
  - https://docs.langchain.com/langsmith/smith-api/workspaces/get-current-active-workspace-members
  - https://docs.langchain.com/langsmith/smith-api/workspaces/get-current-pending-workspace-members
  - https://docs.langchain.com/langsmith/smith-api/workspaces/get-current-workspace-encrypted-secrets
  - https://docs.langchain.com/langsmith/smith-api/workspaces/get-current-workspace-members
  - https://docs.langchain.com/langsmith/smith-api/workspaces/get-current-workspace-stats
  - https://docs.langchain.com/langsmith/smith-api/workspaces/get-current-workspace-usage-limits-info
  - https://docs.langchain.com/langsmith/smith-api/workspaces/get-shared-tokens
  - https://docs.langchain.com/langsmith/smith-api/workspaces/get-tag-key
  - https://docs.langchain.com/langsmith/smith-api/workspaces/get-tag-value
  - https://docs.langchain.com/langsmith/smith-api/workspaces/get-workspace
  - https://docs.langchain.com/langsmith/smith-api/workspaces/list-current-workspace-secrets
  - https://docs.langchain.com/langsmith/smith-api/workspaces/list-pending-workspace-invites
  - https://docs.langchain.com/langsmith/smith-api/workspaces/list-tag-keys
  - https://docs.langchain.com/langsmith/smith-api/workspaces/list-tag-values
  - https://docs.langchain.com/langsmith/smith-api/workspaces/list-taggings
  - https://docs.langchain.com/langsmith/smith-api/workspaces/list-tags
  - https://docs.langchain.com/langsmith/smith-api/workspaces/list-tags-for-resource
  - https://docs.langchain.com/langsmith/smith-api/workspaces/list-tags-for-resources
  - https://docs.langchain.com/langsmith/smith-api/workspaces/list-workspaces
  - https://docs.langchain.com/langsmith/smith-api/workspaces/patch-current-workspace-member
  - https://docs.langchain.com/langsmith/smith-api/workspaces/patch-current-workspace-pending-member
  - https://docs.langchain.com/langsmith/smith-api/workspaces/patch-workspace
  - https://docs.langchain.com/langsmith/smith-api/workspaces/update-tag-key
  - https://docs.langchain.com/langsmith/smith-api/workspaces/update-tag-value
  - https://docs.langchain.com/langsmith/smith-api/workspaces/upsert-current-workspace-secrets
last_verified: 2026-08-11
---

# 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 分为：

1. **TagKey**：key 1–255 字符、可有 description；
2. **TagValue**：属于 key，value 1–255 字符；
3. **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 使用变更单、完整导出、依赖检查、两人批准和删除后审计。