---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - scim
  - service-account
topic: LangSmith Smith API SCIM Tokens、Service Accounts 与 Tenant 兼容层
sources:
  - https://docs.langchain.com/langsmith/smith-api/scim-tokens/create-a-scim-token
  - https://docs.langchain.com/langsmith/smith-api/scim-tokens/delete-a-scim-token
  - https://docs.langchain.com/langsmith/smith-api/scim-tokens/get-a-scim-token
  - https://docs.langchain.com/langsmith/smith-api/scim-tokens/list-scim-tokens
  - https://docs.langchain.com/langsmith/smith-api/scim-tokens/update-a-scim-token
  - https://docs.langchain.com/langsmith/smith-api/service-accounts/create-service-account
  - https://docs.langchain.com/langsmith/smith-api/service-accounts/delete-service-account
  - https://docs.langchain.com/langsmith/smith-api/service-accounts/get-service-accounts
  - https://docs.langchain.com/langsmith/smith-api/tenant/create-tenant
  - https://docs.langchain.com/langsmith/smith-api/tenant/list-tenants
last_verified: 2026-08-11
---

# 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。

## 自动化安全边界

```mermaid
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。