在 OpenAPI 中文档 API 认证¶

本指南展示了如何为您的 LangGraph 平台 API 文档自定义 OpenAPI 安全模式。一个良好记录的安全模式可以帮助 API 消费者了解如何与您的 API 进行身份验证，甚至可以启用自动客户端生成。有关 LangGraph 认证系统的更多详细信息，请参阅认证与访问控制概念指南。

实现 vs 文档

本指南仅涵盖如何在 OpenAPI 中记录您的安全需求。如需实现实际的身份验证逻辑，请参阅如何添加自定义身份验证。

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

默认 Schema¶

默认的安全方案根据部署类型而有所不同：

LangGraph 平台

默认情况下，LangGraph 平台需要在 x-api-key 请求头中提供一个 LangSmith API 密钥：

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
security:
  - apiKeyAuth: []

当使用 LangGraph SDK 时，可以从环境变量中推断出该密钥。

自托管

默认情况下，自托管的部署没有安全方案。这意味着它们只能部署在安全网络上或具有认证机制的环境中。如需添加自定义认证，请参阅如何添加自定义认证。

自定义安全模式¶

要在你的 OpenAPI 文档中自定义安全模式，请在 langgraph.json 文件中的 auth 配置中添加一个 openapi 字段。请注意，这只会更新 API 文档 —— 你还需要在客户端应用程序中实现相应的认证逻辑，如如何添加自定义认证中所示。

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

使用 Bearer Token 的 OAuth2API 密钥

{
  "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"]}
      ]
    }
  }
}

{
  "auth": {
    "path": "./auth.py:my_auth",  // 在此处实现认证逻辑
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [
        {"apiKeyAuth": []}
      ]
    }
  }
}

测试¶

更新配置后：

部署你的应用
访问 /docs 查看更新后的 OpenAPI 文档
使用来自你的认证服务器的凭证尝试访问端点（确保你已先实现认证逻辑）