방화벽 승인 요청

로컬 방화벽 정책이 REQUIRE_APPROVAL을 반환하면 승인 API를 사용합니다. 연결 프로그램은 승인 요청을 한 번 생성하고 제한된 시간 동안 상태를 조회합니다. 결과가 APPROVED일 때만 보호된 도구를 실행합니다. 두 API 모두 안정적인 X-Lynx-Client-ID 헤더가 필요합니다. Lynx는 이 값과 clientRequestId를 함께 사용해 재시도를 중복 처리하지 않고, 다른 SDK 인스턴스가 요청을 조회하지 못하게 합니다.

승인 요청 생성

POST /openapi/v1/firewall-approvals에는 events:write 권한이 필요합니다.

curl --request POST \
  --url https://api.lynxops.co/openapi/v1/firewall-approvals \
  --header "X-API-Key: $LYNX_API_KEY" \
  --header "X-Lynx-Client-ID: support-worker-01" \
  --header "Content-Type: application/json" \
  --data '{
    "clientRequestId": "approval_refund_run_01JZQ3VY4K",
    "runId": "run_01JZQ3VY4K",
    "sessionId": "session_customer_42",
    "agentId": "support-agent",
    "policyId": "17",
    "toolName": "refund",
    "inputHash": "b11c0c8f2dbe3be223af31f44a9faca0f8f5d4ff2595428815ed4de6c56e4f35",
    "reason": "자동 승인 한도를 초과한 환불입니다.",
    "timeoutMs": 300000
  }'

timeoutMs는 1초 이상 24시간 이하여야 합니다. 같은 도구 호출을 재시도할 때는 동일한 clientRequestId를 사용합니다. 다른 호출에는 이 값을 재사용하지 않습니다. API는 현재 승인 상태와 함께 201을 반환합니다.

{
  "id": "2cbde2b2-a22d-4b52-b304-7fe45eec8391",
  "status": "PENDING",
  "expiresAt": "2026-07-25T06:30:00.000Z",
  "decidedAt": null,
  "decisionReason": null
}

승인 상태 조회

GET /openapi/v1/firewall-approvals/{approvalId}에는 policies:read 권한이 필요합니다. 요청을 생성할 때 사용한 것과 같은 X-Lynx-Client-ID를 전달합니다.

curl --request GET \
  --url https://api.lynxops.co/openapi/v1/firewall-approvals/2cbde2b2-a22d-4b52-b304-7fe45eec8391 \
  --header "X-API-Key: $LYNX_API_KEY" \
  --header "X-Lynx-Client-ID: support-worker-01"

상태는 다음 중 하나입니다.

PENDING: 잠시 기다린 후 다시 조회합니다.
APPROVED: inputHash와 연결된 동일한 도구 호출만 실행합니다.
REJECTED: 도구를 실행하지 않습니다.
EXPIRED: 도구를 실행하지 않습니다.

조회 간격은 최소 1초를 권장하며 로컬 제한 시간이 끝나면 조회를 중단합니다. 네트워크 오류, timeout, 잘못된 응답, 알 수 없는 상태가 발생해도 도구 실행을 허용하면 안 됩니다.

권장 흐름

활성 방화벽 정책을 로컬에서 평가합니다.
결과가 REQUIRE_APPROVAL일 때만 승인 요청을 생성합니다.
재시도할 때 승인 ID와 clientRequestId를 유지합니다.
승인, 거절, 만료 또는 로컬 제한 시간까지 상태를 조회합니다.
실행 직전에 도구 이름과 입력 해시가 그대로인지 확인합니다.
승인 결과를 같은 Run과 세션에 기록합니다.

도구 인자와 승인 사유에는 민감정보가 포함될 수 있습니다. 원문 대신 재현 가능한 해시를 보내고, 승인 사유의 비밀값을 마스킹하며, API 키나 승인 자격 정보를 로그에 남기지 않습니다.

시작하기

TypeScript SDK

OpenAPI

방화벽 승인 요청

승인 요청 생성

승인 상태 조회

권장 흐름

​승인 요청 생성

​승인 상태 조회

​권장 흐름

승인 요청 생성

승인 상태 조회

권장 흐름