이 가이드는 LangSmith API 문서의 OpenAPI security schema를 커스터마이징하는 방법을 보여줍니다. 잘 문서화된 security schema는 API 사용자가 API 인증 방법을 이해하는 데 도움이 되며, 자동 client 생성도 가능하게 합니다. LangGraph의 인증 시스템에 대한 자세한 내용은 Authentication & Access Control 개념 가이드를 참조하세요.
구현 vs 문서화 이 가이드는 OpenAPI에서 보안 요구사항을 문서화하는 방법만 다룹니다. 실제 인증 로직을 구현하려면 커스텀 인증 추가 방법을 참조하세요.
이 가이드는 모든 LangSmith 배포(Cloud 및 self-hosted)에 적용됩니다. LangSmith를 사용하지 않고 LangGraph 오픈소스 라이브러리를 사용하는 경우에는 적용되지 않습니다.

​
기본 Schema

기본 security scheme은 배포 유형에 따라 다릅니다:
  • LangSmith
기본적으로 LangSmith는 x-api-key header에 LangSmith API key가 필요합니다: 
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
security:
  - apiKeyAuth: []
LangGraph SDK 중 하나를 사용할 때, 이는 환경 변수에서 추론될 수 있습니다.
  • Self-hosted
기본적으로 self-hosted 배포에는 security scheme이 없습니다. 즉, 보안 네트워크에서만 배포하거나 인증과 함께 배포해야 합니다. 커스텀 인증을 추가하려면 커스텀 인증 추가 방법을 참조하세요.

​
커스텀 Security Schema

OpenAPI 문서에서 security schema를 커스터마이징하려면 langgraph.json의 auth 설정에 openapi 필드를 추가하세요. 이는 API 문서만 업데이트한다는 점을 기억하세요 - 커스텀 인증 추가 방법에 표시된 대로 해당 인증 로직도 구현해야 합니다. LangSmith는 인증 endpoint를 제공하지 않습니다 - 클라이언트 애플리케이션에서 사용자 인증을 처리하고 결과 자격 증명을 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. 인증 서버의 자격 증명을 사용하여 endpoint를 테스트합니다 (먼저 인증 로직을 구현했는지 확인하세요)
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I