> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 API 管理您的组织

LangSmith 的 API 支持通过 API 密钥进行编程访问，涵盖 UI 中所有可用的操作，仅有少数例外情况在[仅限用户的端点](#仅限用户的端点)中注明。

<Check>
  在深入此内容之前，阅读以下内容可能有所帮助：

  * [关于组织和工作区的概念指南](/langsmith/administration-overview)
  * [组织设置操作指南](/langsmith/set-up-hierarchy#set-up-an-organization)
</Check>

<Note>
  有一些限制即将解除：

  * LangSmith SDK 尚不支持这些组织管理操作。
  * 具有组织管理员权限的组织范围[服务密钥](/langsmith/administration-overview#service-keys)可用于执行这些操作。
</Note>

<Warning>
  使用 `X-Tenant-Id` 头来指定目标工作区。如果未提供该头，操作将默认在密钥最初创建的工作区中进行（如果该密钥不是组织范围的）。

  **如果使用组织范围的服务密钥访问工作区范围的资源时未指定 `X-Tenant-Id`，请求将失败并返回 `403 Forbidden`。**
</Warning>

下面列出了一些常用的端点和用例。有关可用端点的完整列表，请参阅 [API 文档](https://api.smith.langchain.com/redoc)。**所有请求都应包含 `X-Organization-Id` 头，而针对特定工作区的请求还应包含 `X-Tenant-Id` 头。**

## 工作区

* [列出工作区](https://api.smith.langchain.com/redoc#tag/workspaces/operation/list_workspaces_api_v1_workspaces_get)
* [创建工作区](https://api.smith.langchain.com/redoc#tag/workspaces/operation/create_workspace_api_v1_workspaces_post)
* [更新工作区名称](https://api.smith.langchain.com/redoc#tag/workspaces/operation/patch_workspace_api_v1_workspaces__workspace_id__patch)

## 用户管理

### 基于角色的访问控制 (RBAC)

* [列出角色](https://api.smith.langchain.com/redoc#tag/orgs/operation/list_organization_roles_api_v1_orgs_current_roles_get)
* [列出权限](https://api.smith.langchain.com/redoc#tag/orgs/operation/update_organization_roles_api_v1_orgs_current_roles__role_id__patch)
* [创建角色](https://api.smith.langchain.com/redoc#tag/orgs/operation/create_organization_roles_api_v1_orgs_current_roles_post)
* [更新角色](https://api.smith.langchain.com/redoc#tag/orgs/operation/update_organization_roles_api_v1_orgs_current_roles__role_id__patch)

### 成员管理

应使用 [RBAC](#rbac) 下的 `列出角色` 来检索这些操作的角色 ID。`列出 [组织|工作区] 成员` 端点（如下）响应中的 `"id"` 应作为这些操作中的 `identity_id` 使用。

组织级别：

* [列出活跃的组织成员](https://api.smith.langchain.com/redoc#tag/orgs/operation/get_current_active_org_members_api_v1_orgs_current_members_active_get)
* [列出待处理的组织成员](https://api.smith.langchain.com/redoc#tag/orgs/operation/get_current_pending_org_members_api_v1_orgs_current_members_pending_get)
* [邀请用户加入组织和一个或多个工作区](https://api.smith.langchain.com/redoc#tag/orgs/operation/add_members_to_current_org_batch_api_v1_orgs_current_members_batch_post)。当用户还不是组织成员时，应使用此端点。
* [更新用户在组织中的角色](https://api.smith.langchain.com/redoc#tag/workspaces/operation/add_member_to_current_workspace_api_v1_workspaces_current_members_post)
* [将某人从组织中移除](https://api.smith.langchain.com/redoc#tag/orgs/operation/remove_member_from_current_org_api_v1_orgs_current_members__identity_id__delete)

工作区级别：

* [列出工作区成员](https://api.smith.langchain.com/redoc#tag/workspaces/operation/get_current_workspace_members_api_v1_workspaces_current_members_get)
* [将已是组织成员的用户添加到工作区](https://api.smith.langchain.com/redoc#tag/workspaces/operation/add_member_to_current_workspace_api_v1_workspaces_current_members_post)
* [更新用户在工作区中的角色](https://api.smith.langchain.com/redoc#tag/workspaces/operation/add_member_to_current_workspace_api_v1_workspaces_current_members_post)
* [将某人从工作区中移除](https://api.smith.langchain.com/redoc#tag/workspaces/operation/delete_current_workspace_member_api_v1_workspaces_current_members__identity_id__delete)

<Note>
  应省略以下参数：`read_only`（已弃用）、`password` 和 `full_name`（仅限[基本认证](/langsmith/authentication-methods)）
</Note>

## API 密钥

* [创建服务密钥](https://api.smith.langchain.com/redoc#tag/api-key/operation/generate_api_key_api_v1_api_key_post)
* [删除服务密钥](https://api.smith.langchain.com/redoc#tag/api-key/operation/delete_api_key_api_v1_api_key__api_key_id__delete)

## 安全设置

<Note>
  进行这些更改需要组织管理员权限。
</Note>

<Note>
  此处的“共享资源”指[公共提示](/langsmith/create-a-prompt#save-your-prompt)、[共享运行](/langsmith/manage-trace#share-a-trace)和[共享数据集](/langsmith/manage-datasets#share-a-dataset)。
</Note>

<Warning>
  更新这些设置会影响**组织中的所有资源**。
</Warning>

您可以在工作区的 **设置 > 共享** 选项卡下更新这些设置，也可以通过 API 更新：

* [更新组织共享设置](https://api.smith.langchain.com/redoc#tag/orgs/operation/update_current_organization_info_api_v1_orgs_current_info_patch)
  * 使用 `unshare_all` 取消共享所选工作区的**所有**共享资源 - 使用 `disable_public_sharing` 防止未来共享资源

这些设置只能通过 API 编辑：

* [禁用/启用个人访问令牌 (PAT) 创建](https://api.smith.langchain.com/redoc#tag/orgs/operation/update_current_organization_info_api_v1_orgs_current_info_patch)（适用于自托管版本，Helm chart 版本 0.11.25+ 可用）
  * 使用 `pat_creation_disabled` 为整个组织禁用 PAT 创建。
  * 有关组织查看者角色（无法创建 PAT）的信息，请参阅[管理员指南](/langsmith/administration-overview#organization-roles)。
  * 对于自托管部署，您还可以使用环境变量[全局禁用所有组织的 PAT 创建](/langsmith/self-host-user-management#disabling-personal-access-token-creation)。

## 仅限用户的端点

这些端点是用户范围的，需要已登录用户的 JWT，因此应仅通过 UI 执行。

* `/api-key/current` 端点：与用户的个人访问令牌 (PAT) 相关
* `/sso/email-verification/send`（仅限云版本）：此端点与 [SAML SSO](/langsmith/user-management) 相关

## 示例代码

下面的示例代码演示了几个与组织管理相关的常见工作流。请确保在代码中出现 `<replace_me>` 的地方进行必要的替换。

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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"。对于自托管安装或欧盟区域，请相应更新
    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"}

    # 邀请用户加入组织和新工作区，作为编辑者。
    # workspace_role_id 仅在启用 RBAC（企业功能）时允许使用。
    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()

    # 将已存在于组织中的用户添加到新工作区，作为查看者。
    # workspace_role_id 仅在启用 RBAC（企业功能）时允许使用。
    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
    )

    # 将用户的工作区角色更新为管理员（仅限企业版）
    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()

    # 将用户的组织角色更新为组织管理员
    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()
```

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/manage-organization-by-api.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>
