> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lynxops.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 방화벽 승인 요청

> 운영자가 승인하거나 거절할 때까지 보호된 도구 호출을 대기시킵니다.

로컬 방화벽 정책이 `REQUIRE_APPROVAL`을 반환하면 승인 API를 사용합니다.
연결 프로그램은 승인 요청을 한 번 생성하고 제한된 시간 동안 상태를
조회합니다. 결과가 `APPROVED`일 때만 보호된 도구를 실행합니다.

두 API 모두 안정적인 `X-Lynx-Client-ID` 헤더가 필요합니다. Lynx는 이 값과
`clientRequestId`를 함께 사용해 재시도를 중복 처리하지 않고, 다른 SDK
인스턴스가 요청을 조회하지 못하게 합니다.

## 승인 요청 생성

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

```bash theme={null}
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`을 반환합니다.

```json theme={null}
{
  "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`를
전달합니다.

```bash theme={null}
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, 잘못된 응답, 알 수 없는 상태가
발생해도 도구 실행을 허용하면 안 됩니다.

## 권장 흐름

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

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