跳到内容

在OpenAPI中记录API认证

本指南展示了如何为您的LangGraph平台API文档定制OpenAPI安全架构。一个文档齐全的安全架构有助于API使用者理解如何对您的API进行认证，甚至可以实现自动客户端生成。有关LangGraph认证系统的更多详细信息，请参阅认证与访问控制概念指南。

实现与文档

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

本指南适用于所有LangGraph平台部署（云端和自托管）。如果您不使用LangGraph平台，则不适用于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。

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

{
  "auth": {
    "path": "./auth.py:my_auth",  // Implement auth logic here
    "openapi": {
      "securitySchemes": {
        "apiKeyAuth": {
          "type": "apiKey",
          "in": "header",
          "name": "X-API-Key"
        }
      },
      "security": [
        {"apiKeyAuth": []}
      ]
    }
  }
}

测试

更新配置后

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