外观
使用 API 管理你的组织
约 1350 字大约 5 分钟
2025-11-28
LangSmith 的 API 通过 API Key 支持对 UI 中可用操作的编程访问,只有少数例外情形在仅限用户的端点中注明。
在阅读本内容之前,建议先参考:
有一些限制很快会解除:
- LangSmith SDK 尚不支持这些组织管理操作。
- 具有 Organization Admin 权限的组织范围服务密钥可用于这些操作。
使用 X-Tenant-Id 请求头指定目标工作区。如果未提供该请求头,且操作不是组织范围,且 API Key 不是组织范围的,操作将默认作用于 API Key 最初创建所在的工作区。
当使用组织范围的 API Key 访问工作区范围资源却未指定 X-Tenant-Id 时,请求将以 403 Forbidden 失败。
下面列出一些常用端点与用例。完整端点列表请参阅API 文档。所有请求都应包含 X-Organization-Id 请求头,对特定工作区范围的请求还应包含 X-Tenant-Id 请求头。
工作区
用户管理
RBAC
成员管理
在下述操作中,List roles(见 RBAC)用于检索角色 ID。List [organization|workspace] members(见下文)端点返回的 "id" 应作为这些操作中的 identity_id。
组织层面:
- 列出活跃的组织成员
- 列出待定的组织成员
- 邀请用户加入组织及一个或多个工作区。当该用户尚不是组织成员时应使用此端点。
- 更新用户的组织角色
- 将某人从组织移除
工作区层面:
这些参数应省略:read_only(已弃用)、password 与 full_name(仅基础认证适用)。
API 密钥
安全设置
进行这些更改需要 Organization Admin 权限。
更新这些设置会影响组织内所有资源。
你可以在工作区的 Settings > Shared 标签下更新这些设置,或通过 API:
- 更新组织共享设置
- 使用
unshare_all取消组织内所有共享资源的共享——使用disable_public_sharing阻止未来共享资源
- 使用
以下设置仅能通过 API 编辑:
- 禁用/启用 PAT 创建(自托管,适用于 Helm chart 版本 0.11.25+)
- 使用
pat_creation_disabled禁用整个组织的 PAT 创建。 - 参阅管理员指南了解 Organization Viewer 角色,其无法创建 PAT。
- 使用
仅限用户的端点
这些端点是用户范围的,需要已登录用户的 JWT,因此应仅通过 UI 执行。
/api-key/current端点:与用户的 PAT 相关/sso/email-verification/send(仅云端):与SAML SSO相关
示例代码
下方示例代码演示与组织管理相关的一些常见工作流。请确保将代码中的 <replace_me> 替换为必要值。
import os
import requests
def main():
api_key = os.environ["LANGSMITH_API_KEY"]
# LANGSMITH_ORGANIZATION_ID 不是 SDK 中的标准环境变量,仅用于此示例
organization_id = os.environ["LANGSMITH_ORGANIZATION_ID"]
base_url = os.environ.get("LANGSMITH_ENDPOINT") # 或 "https://api.smith.langchain.com"。针对自托管安装或 EU 区域请适当更新
headers = {
"Content-Type": "application/json",
"X-API-Key": api_key,
"X-Organization-Id": organization_id,
}
session = requests.Session()
session.headers.update(headers)
workspaces_path = f"{base_url}/api/v1/workspaces"
orgs_path = f"{base_url}/api/v1/orgs/current"
api_keys_path = f"{base_url}/api/v1/api-key"
# 创建工作区
workspace_res = session.post(workspaces_path, json={"display_name": "My Workspace"})
workspace_res.raise_for_status()
workspace = workspace_res.json()
workspace_id = workspace["id"]
new_workspace_headers = {
"X-Tenant-Id": workspace_id,
}
# 获取角色——包括组织与工作区角色
roles_res = session.get(f"{orgs_path}/roles")
roles_res.raise_for_status()
roles = roles_res.json()
# 系统组织角色为 'Organization Admin'、'Organization User'
# 系统工作区角色为 'Admin'、'Editor'、'Viewer'
org_roles_by_name = {role["display_name"]: role for role in roles if role["access_scope"] == "organization"}
ws_roles_by_name = {role["display_name"]: role for role in roles if role["access_scope"] == "workspace"}
# 邀请用户加入组织与新工作区,作为 Editor。
# 仅在启用 RBAC(企业功能)时允许 workspace_role_id。
new_user_email = "<replace_me>"
new_user_res = session.post(
f"{orgs_path}/members",
json={
"email": new_user_email,
"role_id": org_roles_by_name["Organization User"]["id"],
"workspace_ids": [workspace_id],
"workspace_role_id": ws_roles_by_name["Editor"]["id"],
},
)
new_user_res.raise_for_status()
# 将组织内已存在的用户添加到新工作区,作为 Viewer。
# 仅在启用 RBAC(企业功能)时允许 workspace_role_id。
existing_user_email = "<replace_me>"
org_members_res = session.get(f"{orgs_path}/members")
org_members_res.raise_for_status()
org_members = org_members_res.json()
existing_org_member = next(
(member for member in org_members["members"] if member["email"] == existing_user_email), None
)
existing_user_res = session.post(
f"{workspaces_path}/current/members",
json={
"user_id": existing_org_member["user_id"],
"workspace_ids": [workspace_id],
"workspace_role_id": ws_roles_by_name["Viewer"]["id"],
},
headers=new_workspace_headers,
)
existing_user_res.raise_for_status()
# 列出该工作区的所有成员
members_res = session.get(f"{workspaces_path}/current/members", headers=new_workspace_headers)
members_res.raise_for_status()
members = members_res.json()
workspace_member = next(
(member for member in members["members"] if member["email"] == existing_user_email), None
)
# 将该用户的工作区角色更新为 Admin(仅企业版)
existing_user_id = workspace_member["id"]
update_res = session.patch(
f"{workspaces_path}/current/members/{existing_user_id}",
json={"role_id": ws_roles_by_name["Admin"]["id"]},
headers=new_workspace_headers,
)
update_res.raise_for_status()
# 将该用户的组织角色更新为 Organization Admin
update_res = session.patch(
f"{orgs_path}/members/{existing_org_member['id']}",
json={"role_id": org_roles_by_name["Organization Admin"]["id"]},
)
update_res.raise_for_status()
# 创建新的服务密钥
api_key_res = session.post(
api_keys_path,
json={"description": "my key"},
headers=new_workspace_headers,
)
api_key_res.raise_for_status()
api_key_json = api_key_res.json()
api_key = api_key_json["key"]
if __name__ == "__main__":
main()