在 OpenAPI 中记录 API 认证¶

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

实现 vs 文档

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

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

默认模式¶

默认安全模式因部署类型而异：

LangGraph Platform

默认情况下，LangGraph Platform 需要在 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 Platform 不提供认证端点 - 你需要在客户端应用中处理用户认证，并将生成的凭证传递给 LangGraph API。

PythonOAuth2 Bearer TokenAPI KeyJavaScriptOAuth2 Bearer TokenAPI Key

{
  "auth": {
    "path": "./auth.py:my_auth",  // 在此实现认证逻辑
    "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"]}
      ]
    }
  }
}

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

{
  "auth": {
    "path": "./auth.ts:my_auth",  // 在此实现认证逻辑
    "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"]}
      ]
    }
  }
}

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

测试¶

更新配置后：

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