本指南讲解如何为 LangSmith API 文档自定义 OpenAPI 安全方案。完善的安全方案能帮助 API 使用者了解认证方式，甚至支持自动生成客户端。更多关于 LangGraph 认证系统的细节，请参阅身份验证与访问控制概念指南。
实现 vs 文档 本文仅介绍如何在 OpenAPI 中记录安全要求。若要实现实际的认证逻辑，请参考如何添加自定义认证。
该指南适用于所有 LangSmith 部署（云端与自托管）。若仅使用 LangGraph 开源库而不依赖 LangSmith，则不在此列。

​
默认安全方案

默认安全方案会随部署类型而变化：
  • LangSmith
默认情况下，LangSmith 需要在 x-api-key 请求头里提供 LangSmith API Key： 
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
security:
  - apiKeyAuth: []
使用 LangGraph SDK 时，可自动从环境变量推断该配置。
  • Self-hosted
默认情况下，自托管部署不会开启安全方案，因此应部署在已受保护的网络或配套认证机制的环境中。如需添加自定义认证，请参考如何添加自定义认证。

​
自定义安全方案

若要在 OpenAPI 文档中自定义安全方案，请在 langgraph.json 的 auth 配置中添加 openapi 字段。请注意，这只会更新 API 文档；你仍需按如何添加自定义认证中的步骤实现对应的认证逻辑。 需要注意的是，LangSmith 不提供认证端点，用户认证需在客户端或外部服务中完成，再将凭证传递给 LangGraph API。
  • OAuth2 with Bearer Token
  • API Key
{
  "auth": {
    "path": "./auth.py:my_auth",  // Implement auth logic here
    "openapi": {
      "securitySchemes": {
        "OAuth2": {
          "type": "oauth2",
          "flows": {
            "implicit": {
              "authorizationUrl": "https://your-auth-server.com/oauth/authorize",
              "scopes": {
                "me": "Read information about the current user",
                "threads": "Access to create and manage threads"
              }
            }
          }
        }
      },
      "security": [
        {"OAuth2": ["me", "threads"]}
      ]
    }
  }
}

​
测试步骤

更新配置后：
  1. 部署应用
  2. 访问 /docs，查看更新后的 OpenAPI 文档
  3. 使用认证服务器生成的凭证测试各端点（前提是认证逻辑已正确实现）
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.