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

# 在 OpenAPI 中记录 API 认证

本指南展示了如何为您的 LangSmith API 文档自定义 OpenAPI 安全模式。一个文档完善的安全模式有助于 API 使用者理解如何对您的 API 进行身份验证，甚至支持自动生成客户端。有关 LangGraph 认证系统的更多详细信息，请参阅[认证与访问控制概念指南](/langsmith/auth)。

<Note>
  **实现与文档**
  本指南仅涵盖如何在 OpenAPI 中记录您的安全要求。要实现实际的认证逻辑，请参阅[如何添加自定义认证](/langsmith/custom-auth)。
</Note>

本指南适用于所有 LangSmith 部署（云端和自托管）。如果您未使用 LangSmith，则不适用于 LangGraph 开源库的使用。

## 默认模式

默认的安全方案因部署类型而异：

<Tabs>
  <Tab title="LangSmith" />
</Tabs>

默认情况下，LangSmith 要求在 `x-api-key` 请求头中提供 LangSmith API 密钥：

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
security:
  - apiKeyAuth: []
```

当使用 LangGraph SDK 之一时，这可以从环境变量中推断。

<Tabs>
  <Tab title="自托管" />
</Tabs>

默认情况下，自托管部署没有安全方案。这意味着它们应仅部署在安全网络中或配合认证使用。要添加自定义认证，请参阅[如何添加自定义认证](/langsmith/custom-auth)。

## 自定义安全模式

要在 OpenAPI 文档中自定义安全模式，请在 `langgraph.json` 的 `auth` 配置中添加一个 `openapi` 字段。请注意，这仅更新 API 文档——您还必须实现相应的认证逻辑，如[如何添加自定义认证](/langsmith/custom-auth)中所示。

请注意，LangSmith 不提供认证端点——您需要在客户端应用程序中处理用户认证，并将生成的凭据传递给 LangGraph API。

<Tabs>
  <Tab title="OAuth2 与 Bearer Token">
    ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "auth": {
        "path": "./auth.py:my_auth",  // 在此处实现认证逻辑
        "openapi": {
          "securitySchemes": {
            "OAuth2": {
              "type": "oauth2",
              "flows": {
                "implicit": {
                  "authorizationUrl": "https://your-auth-server.com/oauth/authorize",
                  "scopes": {
                    "me": "读取当前用户信息",
                    "threads": "访问以创建和管理线程"
                  }
                }
              }
            }
          },
          "security": [
            {"OAuth2": ["me", "threads"]}
          ]
        }
      }
    }
    ```
  </Tab>

  <Tab title="API 密钥">
    ```json theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    {
      "auth": {
        "path": "./auth.py:my_auth",  // 在此处实现认证逻辑
        "openapi": {
          "securitySchemes": {
            "apiKeyAuth": {
              "type": "apiKey",
              "in": "header",
              "name": "X-API-Key"
            }
          },
          "security": [
            {"apiKeyAuth": []}
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 测试

更新配置后：

1. 部署您的应用程序
2. 访问 `/docs` 查看更新后的 OpenAPI 文档
3. 使用来自您认证服务器的凭据尝试调用端点（请确保您已首先实现认证逻辑）

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\openapi-security.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>