# 감사 내보내기 생성

`POST /v1/audit-exports` · 권한 `audit-exports:write`

일치하는 감사 레코드를 서명된 패키지에 기록하는 작업을 큐에 넣습니다. 이 패키지는 KeenAuth를 신뢰하지 않고도 검증할 수 있습니다. 작업은 `202 Accepted`와 함께 반환됩니다. [감사 내보내기 조회](get.md)로 작업을 확인하고 [감사 내보내기 다운로드](download.md)로 파일을 가져오십시오.

API 키(비밀 키 또는 제한된 키)만 내보내기를 생성할 수 있습니다. 작업에는 키가 `requested_by`로 기록됩니다. 환경은 키에서 결정됩니다.

## 요청

`Idempotency-Key`는 필수입니다(16~64자, `A-Z a-z 0-9 _ -`). 같은 키와 같은 본문으로 요청하면 `Idempotent-Replayed: true`와 함께 첫 번째 작업이 반환됩니다. 같은 키에 다른 본문을 보내면 `422 idempotency_key_reuse`로 실패합니다. SDK와 CLI가 이 헤더를 자동으로 설정합니다.

필터는 [감사 이벤트 목록](../audit-events/list.md)과 같습니다. 생략한 필드는 필터링에 사용되지 않습니다. 차이점은 다음과 같습니다:

| 필드 | 유형 | 설명 |
|---|---|---|
| `stream` | string | `admin`(기본값) 또는 `application`. |
| `from` | RFC 3339 | 하한(포함). 기본값은 보존 기간의 시작입니다. 92일 제한은 없으며, 패키지에는 최대 5천만 줄(자리 표시자 포함)이 들어갑니다. |
| `to` | RFC 3339 | 상한(제외). 기본값은 현재 시각이며, 미래 시각일 수 없습니다. |
| `action`, `category`, `actor_type`, `actor_id`, `target_type`, `target_id`, `org_id`, `outcome`, `request_id`, `correlation_id`, `agent_only` | | 목록 필터와 같습니다. 목록의 `client` 필터는 여기서 사용할 수 없으며, `client` 필드를 보내면 `400 unknown_field`로 실패합니다. |
| `include_ip` | boolean | 생성 후 13개월 이내의 레코드에 전체 IP 주소와 사용자 에이전트를 추가합니다. `audit-events:read_ip` 권한도 필요합니다. 기본값은 `false`입니다. |

```json
{
  "stream": "admin",
  "from": "2026-07-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "action": "user."
}
```

환경별로 동시에 실행되는 작업은 최대 3개입니다(개발 및 스테이징 환경에서는 1개).

## 응답

`202 Accepted`와 `status`가 `queued`인 작업이 반환됩니다. `filter`에는 `from`과 `to`의 기본값이 채워진 적용 필터가 표시됩니다. `recorded_before`는 스냅숏 상한으로, 이 시각 이전에 저장된 레코드만 패키지에 포함됩니다.

```json
{
  "id": "aex_01j9xk3m7q8r2s4t6v8w0y2z4e",
  "status": "queued",
  "filter": {
    "stream": "admin",
    "from": "2026-07-01T00:00:00Z",
    "to": "2026-10-01T00:00:00Z",
    "action": "user.",
    "category": null,
    "actor_type": null,
    "actor_id": null,
    "target_type": null,
    "target_id": null,
    "org_id": null,
    "outcome": null,
    "request_id": null,
    "correlation_id": null,
    "agent_only": false
  },
  "include_ip": false,
  "record_count": null,
  "file": null,
  "manifest_sha256": null,
  "failure_reason": null,
  "created_at": "2026-10-19T09:00:00Z",
  "started_at": null,
  "completed_at": null,
  "expires_at": null,
  "recorded_before": "2026-10-19T09:00:00Z",
  "requested_by": {"type": "api_key", "id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d"}
}
```

## 오류

모든 오류는 안정적인 `code`가 포함된 `application/problem+json` 본문으로 반환됩니다.

| HTTP | `code` | 발생 조건 |
|---|---|---|
| 400 | `malformed_request` | `Idempotency-Key`가 없거나 형식이 잘못되었거나, 본문이 올바른 JSON이 아닙니다. |
| 400 | `unknown_field` | 본문에 위에 나열되지 않은 필드가 있습니다. |
| 400 | `invalid_filter` | 감사 서비스가 필터를 거부했습니다(예: 미래 시각의 `to`). |
| 400 | `range_outside_retention` | `from` 또는 `to`가 요금제의 감사 보존 기간 밖에 있습니다. |
| 422 | `validation_failed` | 필드가 유효하지 않습니다(잘못된 유형, 잘못된 타임스탬프, `from`보다 이전인 `to`, 알 수 없는 열거형 값, 형식이 잘못된 ID, 빈 문자열). |
| 422 | `idempotency_key_reuse` | 다른 본문과 함께 `Idempotency-Key`를 재사용했습니다. |
| 401 | `unauthenticated` | API 키가 없거나 유효하지 않거나 폐기되었습니다. |
| 403 | `insufficient_permissions` | 키에 `audit-exports:write` 권한이 없거나, `audit-events:read_ip` 없이 `include_ip`를 사용했거나(`required_permissions`에 두 권한이 모두 표시됩니다), 호출자가 API 키가 아닙니다. |
| 429 | `rate_limited` | 이 환경에서 실행 중인 작업이 너무 많거나 요청 한도를 초과했습니다. `Retry-After`를 준수하십시오. |
| 503 | `service_unavailable` | 종속 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하십시오. |

## 예시

```bash
curl https://api.eu.keenauth.com/v1/audit-exports \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-07-01T00:00:00Z", "to": "2026-10-01T00:00:00Z", "action": "user."}'
```

```bash
keenauth audit-exports create --from 2026-07-01T00:00:00Z --to 2026-10-01T00:00:00Z --action user.
```

## 개인정보

이 엔드포인트는 개인정보인 감사 이벤트를 다룹니다. [KeenAuth API의 개인정보](/docs/policies/personal-data)에서 저장되는 항목, 보관 기간 및 삭제 방법을 확인하십시오. 어떤 필드에도 특수 범주의 개인정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.