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()